package_manager/src/PathExcluder/UnknownPathExcluder.php

@@ -5,9 +5,15 @@ declare(strict_types = 1);
 namespace Drupal\package_manager\PathExcluder;
 
 use Drupal\Component\Serialization\Json;
+use Drupal\Core\Config\ConfigFactoryInterface;
+use Drupal\Core\StringTranslation\StringTranslationTrait;
 use Drupal\package_manager\ComposerInspector;
 use Drupal\package_manager\Event\CollectPathsToExcludeEvent;
+use Drupal\package_manager\Event\StatusCheckEvent;
 use Drupal\package_manager\PathLocator;
+use Psr\Log\LoggerAwareInterface;
+use Psr\Log\LoggerAwareTrait;
+use Psr\Log\NullLogger;
 use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 
 /**
@@ -23,12 +29,22 @@ use Symfony\Component\EventDispatcher\EventSubscriberInterface;
  *
  * If web root and project root are the same, nothing is excluded.
  *
+ * This excluder can be disabled by changing the config setting
+ * `package_manager.settings:include_unknown_files_in_project_root` to TRUE.
+ * This may be needed for sites that have files outside the web root (besides
+ * the vendor directory) which are nonetheless needed in order for Composer to
+ * assemble the code base correctly; a classic example would be a directory of
+ * patch files used by `cweagans/composer-patches`.
+ *
  * @internal
  *   This is an internal part of Package Manager and may be changed or removed
  *   at any time without warning. External code should not interact with this
  *   class.
  */
-final class UnknownPathExcluder implements EventSubscriberInterface {
+final class UnknownPathExcluder implements EventSubscriberInterface, LoggerAwareInterface {
+
+  use LoggerAwareTrait;
+  use StringTranslationTrait;
 
   /**
    * Constructs a UnknownPathExcluder object.
@@ -37,11 +53,16 @@ final class UnknownPathExcluder implements EventSubscriberInterface {
    *   The Composer inspector service.
    * @param \Drupal\package_manager\PathLocator $pathLocator
    *   The path locator service.
+   * @param \Drupal\Core\Config\ConfigFactoryInterface $configFactory
+   *   The config factory service.
    */
   public function __construct(
     private readonly ComposerInspector $composerInspector,
     private readonly PathLocator $pathLocator,
-  ) {}
+    private readonly ConfigFactoryInterface $configFactory,
+  ) {
+    $this->setLogger(new NullLogger());
+  }
 
   /**
    * {@inheritdoc}
@@ -49,53 +70,110 @@ final class UnknownPathExcluder implements EventSubscriberInterface {
   public static function getSubscribedEvents(): array {
     return [
       CollectPathsToExcludeEvent::class => 'excludeUnknownPaths',
+      StatusCheckEvent::class => 'logExcludedPaths',
     ];
   }
 
   /**
-   * Excludes unknown paths from stage operations.
+   * Returns the paths to exclude from stage operations.
    *
-   * @param \Drupal\package_manager\Event\CollectPathsToExcludeEvent $event
-   *   The event object.
+   * @return string[]
+   *   The paths that should be excluded from stage operations, relative to the
+   *   project root.
    *
    * @throws \Exception
    *   See \Drupal\package_manager\ComposerInspector::validate().
    */
-  public function excludeUnknownPaths(CollectPathsToExcludeEvent $event): void {
-    $project_root = $this->pathLocator->getProjectRoot();
-    $web_root = $project_root . DIRECTORY_SEPARATOR . $this->pathLocator->getWebRoot();
-    if (realpath($web_root) === $project_root) {
-      return;
+  private function getExcludedPaths(): array {
+    // If this excluder is disabled, or the project root and web root are the
+    // same, we are not excluding any paths.
+    $is_disabled = $this->configFactory->get('package_manager.settings')
+      ->get('include_unknown_files_in_project_root');
+    $web_root = $this->pathLocator->getWebRoot();
+    if ($is_disabled || empty($web_root)) {
+      return [];
     }
 
-    // To determine the scaffold files to exclude, the installed packages must
-    // be known, and that requires Composer commands to be able to run. This
-    // intentionally does not catch exceptions: failed Composer validation in
-    // the project root implies that this excluder cannot function correctly.
-    // Note: the call to ComposerInspector::getInstalledPackagesList() would
+    // To determine the files to include, the installed packages must be known,
+    // and that requires Composer commands to be able to run. This intentionally
+    // does not catch exceptions: failed Composer validation in the project root
+    // implies that this excluder cannot function correctly.
+    // Note: the call to ComposerInspector::getConfig() would
     // also have triggered this, but explicitness is preferred here.
     // @see \Drupal\package_manager\StatusCheckTrait::runStatusCheck()
+    $project_root = $this->pathLocator->getProjectRoot();
     $this->composerInspector->validate($project_root);
 
-    $vendor_dir = $this->pathLocator->getVendorDirectory();
-    $scaffold_files_paths = $this->getScaffoldFiles();
-    // Search for all files (including hidden ones) in project root.
-    $paths_in_project_root = glob("$project_root/{,.}*", GLOB_BRACE);
-    $paths = [];
-    $known_paths = array_merge([$vendor_dir, $web_root, "$project_root/composer.json", "$project_root/composer.lock"], $scaffold_files_paths);
-    foreach ($paths_in_project_root as $path_in_project_root) {
-      if (!in_array($path_in_project_root, $known_paths, TRUE)) {
-        $paths[] = $path_in_project_root;
+    // The vendor directory and web root are always included in staging
+    // operations, along with `composer.json`, `composer.lock`, and any scaffold
+    // files provided by Drupal core.
+    $always_include = [
+      $this->composerInspector->getConfig('vendor-dir', $project_root),
+      $web_root,
+      'composer.json',
+      'composer.lock',
+    ];
+    foreach ($this->getScaffoldFiles() as $scaffold_file_path) {
+      // The web root is always included in staging operations, so we don't need
+      // to do anything special for scaffold files that live in it.
+      if (str_starts_with($scaffold_file_path, '[web-root]')) {
+        continue;
       }
+      $always_include[] = ltrim($scaffold_file_path, '/');
+    }
+
+    // Search for all files (including hidden ones) in the project root. We need
+    // to use readdir() and friends here, rather than glob(), since certain
+    // glob() flags aren't supported on all systems. We also can't use
+    // \Drupal\Core\File\FileSystemInterface::scanDirectory(), because it
+    // unconditionally ignores hidden files and directories.
+    $files_in_project_root = [];
+    $handle = opendir($project_root);
+    if (empty($handle)) {
+      throw new \RuntimeException("Could not scan for files in the project root.");
+    }
+    while ($entry = readdir($handle)) {
+      $files_in_project_root[] = $entry;
+    }
+    closedir($handle);
+
+    return array_diff($files_in_project_root, $always_include, ['.', '..']);
+  }
+
+  /**
+   * Excludes unknown paths from stage operations.
+   *
+   * @param \Drupal\package_manager\Event\CollectPathsToExcludeEvent $event
+   *   The event object.
+   */
+  public function excludeUnknownPaths(CollectPathsToExcludeEvent $event): void {
+    // We can exclude the paths as-is; they are already relative to the project
+    // root.
+    $event->add(...$this->getExcludedPaths());
+  }
+
+  /**
+   * Logs the paths that will be excluded from stage operations.
+   */
+  public function logExcludedPaths(): void {
+    $excluded_paths = $this->getExcludedPaths();
+    if ($excluded_paths) {
+      sort($excluded_paths);
+
+      $message = $this->t("The following paths in @project_root aren't recognized as part of your Drupal site, so to be safe, Package Manager is excluding them from all stage operations. If these files are not needed for Composer to work properly in your site, no action is needed. Otherwise, you can disable this behavior by setting the <code>package_manager.settings:include_unknown_files_in_project_root</code> config setting to <code>TRUE</code>.\n\n@list", [
+        '@project_root' => $this->pathLocator->getProjectRoot(),
+        '@list' => implode("\n", $excluded_paths),
+      ]);
+      $this->logger->info($message);
     }
-    $event->addPathsRelativeToProjectRoot($paths);
   }
 
   /**
    * Gets the path of scaffold files, for example 'index.php' and 'robots.txt'.
    *
-   * @return array
-   *   The array of scaffold file paths.
+   * @return string[]
+   *   The paths of scaffold files provided by `drupal/core`, relative to the
+   *   project root.
    *
    * @todo Intelligently load scaffold files in https://drupal.org/i/3343802.
    */
@@ -103,10 +181,9 @@ final class UnknownPathExcluder implements EventSubscriberInterface {
     $project_root = $this->pathLocator->getProjectRoot();
     $packages = $this->composerInspector->getInstalledPackagesList($project_root);
     $extra = Json::decode($this->composerInspector->getConfig('extra', $packages['drupal/core']->path . '/composer.json'));
-    if (isset($extra['drupal-scaffold']['file-mapping'])) {
-      return array_keys($extra['drupal-scaffold']['file-mapping']);
-    }
-    return [];
+
+    $scaffold_files = $extra['drupal-scaffold']['file-mapping'] ?? [];
+    return str_replace('[project-root]', '', array_keys($scaffold_files));
   }
 
 }

package_manager/src/Plugin/QueueWorker/Cleaner.php

+<?php
+
+namespace Drupal\package_manager\Plugin\QueueWorker;
+
+use Drupal\Core\File\FileSystemInterface;
+use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
+use Drupal\Core\Queue\QueueWorkerBase;
+use Symfony\Component\DependencyInjection\ContainerInterface;
+
+/**
+ * Processes a queue of defunct stage directories, deleting them.
+ *
+ * @QueueWorker(
+ *   id = "package_manager_cleanup",
+ *   title = @Translation("Stage directory cleaner"),
+ *   cron = {"time" = 30}
+ * )
+ */
+final class Cleaner extends QueueWorkerBase implements ContainerFactoryPluginInterface {
+
+  /**
+   * Constructs a new Cleaner instance.
+   *
+   * @param array $configuration
+   *   A configuration array containing information about the plugin instance.
+   * @param string $plugin_id
+   *   The plugin ID.
+   * @param mixed $plugin_definition
+   *   The plugin implementation definition.
+   * @param \Drupal\Core\File\FileSystemInterface $fileSystem
+   *   The file system service.
+   */
+  public function __construct(array $configuration, string $plugin_id, mixed $plugin_definition, private readonly FileSystemInterface $fileSystem) {
+    parent::__construct($configuration, $plugin_id, $plugin_definition);
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public static function create(ContainerInterface $container, array $configuration, $plugin_id, $plugin_definition) {
+    return new static(
+      $configuration,
+      $plugin_id,
+      $plugin_definition,
+      $container->get(FileSystemInterface::class),
+    );
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function processItem($dir) {
+    assert(is_string($dir));
+
+    if (file_exists($dir)) {
+      $this->fileSystem->deleteRecursive($dir, function (string $path): void {
+        $this->fileSystem->chmod($path, is_dir($path) ? 0700 : 0600);
+      });
+    }
+  }
+
+}

package_manager/src/ProcessFactory.php

@@ -7,8 +7,7 @@ namespace Drupal\package_manager;
 use Drupal\Core\Config\ConfigFactoryInterface;
 use Drupal\Core\File\FileSystemInterface;
 use PhpTuf\ComposerStager\API\Process\Factory\ProcessFactoryInterface;
-use PhpTuf\ComposerStager\Internal\Process\Factory\ProcessFactory as StagerProcessFactory;
-use Symfony\Component\Process\Process;
+use PhpTuf\ComposerStager\API\Process\Service\ProcessInterface;
 
 // cspell:ignore BINDIR
 
@@ -29,13 +28,13 @@ final class ProcessFactory implements ProcessFactoryInterface {
    *   The file system service.
    * @param \Drupal\Core\Config\ConfigFactoryInterface $configFactory
    *   The config factory service.
-   * @param \PhpTuf\ComposerStager\Internal\Process\Factory\ProcessFactory $decorated
+   * @param \PhpTuf\ComposerStager\API\Process\Factory\ProcessFactoryInterface $decorated
    *   The decorated process factory service.
    */
   public function __construct(
     private readonly FileSystemInterface $fileSystem,
     private readonly ConfigFactoryInterface $configFactory,
-    private readonly StagerProcessFactory $decorated,
+    private readonly ProcessFactoryInterface $decorated,
   ) {}
 
   /**
@@ -57,7 +56,7 @@ final class ProcessFactory implements ProcessFactoryInterface {
   /**
    * {@inheritdoc}
    */
-  public function create(array $command): Process {
+  public function create(array $command): ProcessInterface {
     $process = $this->decorated->create($command);
 
     $env = $process->getEnv();

package_manager/src/ProcessOutputCallback.php

@@ -4,7 +4,8 @@ declare(strict_types = 1);
 
 namespace Drupal\package_manager;
 
-use PhpTuf\ComposerStager\API\Process\Service\ProcessOutputCallbackInterface;
+use PhpTuf\ComposerStager\API\Process\Service\OutputCallbackInterface;
+use PhpTuf\ComposerStager\API\Process\Value\OutputTypeEnum;
 use Psr\Log\LoggerAwareInterface;
 use Psr\Log\LoggerAwareTrait;
 use Psr\Log\NullLogger;
@@ -19,7 +20,7 @@ use Psr\Log\NullLogger;
  *   at any time without warning. External code should not interact with this
  *   class.
  */
-final class ProcessOutputCallback implements ProcessOutputCallbackInterface, LoggerAwareInterface {
+final class ProcessOutputCallback implements OutputCallbackInterface, LoggerAwareInterface {
 
   use LoggerAwareTrait;
 
@@ -47,20 +48,14 @@ final class ProcessOutputCallback implements ProcessOutputCallbackInterface, Log
   /**
    * {@inheritdoc}
    */
-  public function __invoke(string $type, string $buffer): void {
-    // \Symfony\Component\Process\Process defines the output types in lowercase,
-    // but Composer Stager uses uppercase.
-    $type = strtoupper($type);
+  public function __invoke(OutputTypeEnum $type, string $buffer): void {
 
-    if ($type === self::OUT) {
+    if ($type === OutputTypeEnum::OUT) {
       $this->outBuffer .= $buffer;
     }
-    elseif ($type === self::ERR) {
+    elseif ($type === OutputTypeEnum::ERR) {
       $this->errorBuffer .= $buffer;
     }
-    else {
-      throw new \InvalidArgumentException("Unsupported output type: '$type'");
-    }
   }
 
   /**

package_manager/src/ProjectInfo.php

@@ -192,7 +192,7 @@ final class ProjectInfo {
     // update processor service.
     if (!isset($available_projects[$this->name])) {
       /** @var \Drupal\package_manager\PackageManagerUpdateProcessor $update_processor */
-      $update_processor = \Drupal::service('package_manager.update_processor');
+      $update_processor = \Drupal::service(PackageManagerUpdateProcessor::class);
       if ($project_data = $update_processor->getProjectData($this->name)) {
         $available_projects[$this->name] = $project_data;
       }

package_manager/src/StageBase.php

@@ -6,21 +6,19 @@ namespace Drupal\package_manager;
 
 use Composer\Semver\VersionParser;
 use Drupal\Component\Datetime\TimeInterface;
-use Drupal\Component\Utility\Crypt;
-use Drupal\Core\File\Exception\FileException;
-use Drupal\Core\File\FileSystemInterface;
+use Drupal\Component\Utility\Random;
+use Drupal\Core\Queue\QueueFactory;
 use Drupal\Core\StringTranslation\StringTranslationTrait;
 use Drupal\Core\StringTranslation\TranslatableMarkup;
 use Drupal\Core\TempStore\SharedTempStore;
 use Drupal\Core\TempStore\SharedTempStoreFactory;
+use Drupal\Core\Utility\Error;
 use Drupal\package_manager\Event\CollectPathsToExcludeEvent;
 use Drupal\package_manager\Event\PostApplyEvent;
 use Drupal\package_manager\Event\PostCreateEvent;
-use Drupal\package_manager\Event\PostDestroyEvent;
 use Drupal\package_manager\Event\PostRequireEvent;
 use Drupal\package_manager\Event\PreApplyEvent;
 use Drupal\package_manager\Event\PreCreateEvent;
-use Drupal\package_manager\Event\PreDestroyEvent;
 use Drupal\package_manager\Event\PreOperationStageEvent;
 use Drupal\package_manager\Event\PreRequireEvent;
 use Drupal\package_manager\Event\StageEvent;
@@ -34,7 +32,7 @@ use PhpTuf\ComposerStager\API\Core\StagerInterface;
 use PhpTuf\ComposerStager\API\Exception\InvalidArgumentException;
 use PhpTuf\ComposerStager\API\Exception\PreconditionException;
 use PhpTuf\ComposerStager\API\Path\Factory\PathFactoryInterface;
-use PhpTuf\ComposerStager\API\Path\Value\PathList;
+use PhpTuf\ComposerStager\API\Path\Value\PathListInterface;
 use Psr\Log\LoggerAwareInterface;
 use Psr\Log\LoggerAwareTrait;
 use Psr\Log\NullLogger;
@@ -161,6 +159,17 @@ abstract class StageBase implements LoggerAwareInterface {
    */
   protected SharedTempStore $tempStore;
 
+  /**
+   * The stage type.
+   *
+   * To ensure that stage classes do not unintentionally use another stage's
+   * type, all concrete subclasses MUST explicitly define this property.
+   * The recommended pattern is `MODULE:TYPE`.
+   *
+   * @var string
+   */
+  protected string $type;
+
   /**
    * Constructs a new Stage object.
    *
@@ -172,8 +181,8 @@ abstract class StageBase implements LoggerAwareInterface {
    *   The stager service.
    * @param \PhpTuf\ComposerStager\API\Core\CommitterInterface $committer
    *   The committer service.
-   * @param \Drupal\Core\File\FileSystemInterface $fileSystem
-   *   The file system service.
+   * @param \Drupal\Core\Queue\QueueFactory $queueFactory
+   *   The queue factory.
    * @param \Symfony\Contracts\EventDispatcher\EventDispatcherInterface $eventDispatcher
    *   The event dispatcher service.
    * @param \Drupal\Core\TempStore\SharedTempStoreFactory $tempStoreFactory
@@ -190,7 +199,7 @@ abstract class StageBase implements LoggerAwareInterface {
     protected readonly BeginnerInterface $beginner,
     protected readonly StagerInterface $stager,
     protected readonly CommitterInterface $committer,
-    protected readonly FileSystemInterface $fileSystem,
+    protected readonly QueueFactory $queueFactory,
     protected EventDispatcherInterface $eventDispatcher,
     protected readonly SharedTempStoreFactory $tempStoreFactory,
     protected readonly TimeInterface $time,
@@ -201,6 +210,31 @@ abstract class StageBase implements LoggerAwareInterface {
     $this->setLogger(new NullLogger());
   }
 
+  /**
+   * Gets the stage type.
+   *
+   * The stage type can be used by stage event subscribers to implement logic
+   * specific to certain stages, without relying on the class name (which may
+   * not be part of module's public API).
+   *
+   * @return string
+   *   The stage type.
+   *
+   * @throws \LogicException
+   *   Thrown if $this->type is not explicitly overridden.
+   */
+  final public function getType(): string {
+    $reflector = new \ReflectionProperty($this, 'type');
+
+    // The $type property must ALWAYS be overridden. This means that different
+    // subclasses can return the same value (thus allowing one stage to
+    // impersonate another one), but if that happens, it is intentional.
+    if ($reflector->getDeclaringClass()->getName() === static::class) {
+      return $this->type;
+    }
+    throw new \LogicException(static::class . ' must explicitly override the $type property.');
+  }
+
   /**
    * Determines if the stage directory can be created.
    *
@@ -254,7 +288,7 @@ abstract class StageBase implements LoggerAwareInterface {
   /**
    * Collects paths that Composer Stager should exclude.
    *
-   * @return string[]
+   * @return \PhpTuf\ComposerStager\API\Path\Value\PathListInterface
    *   A list of paths that Composer Stager should exclude when creating the
    *   stage directory and applying staged changes to the active directory.
    *
@@ -264,15 +298,14 @@ abstract class StageBase implements LoggerAwareInterface {
    * @see ::create()
    * @see ::apply()
    */
-  protected function getPathsToExclude(): array {
+  protected function getPathsToExclude(): PathListInterface {
     $event = new CollectPathsToExcludeEvent($this, $this->pathLocator, $this->pathFactory);
     try {
-      $this->eventDispatcher->dispatch($event);
+      return $this->eventDispatcher->dispatch($event);
     }
     catch (\Throwable $e) {
       $this->rethrowAsStageException($e);
     }
-    return $event->getAll();
   }
 
   /**
@@ -311,26 +344,40 @@ abstract class StageBase implements LoggerAwareInterface {
     // to create a stage directory at around the same time. If an error occurs
     // while the event is being processed, the stage is marked as available.
     // @see ::dispatch()
-    $id = Crypt::randomBytesBase64();
+    // We specifically generate a random 32-character alphanumeric name in order
+    // to guarantee that the the stage ID won't start with -, which could cause
+    // it to be interpreted as an option if it's used as a command-line
+    // argument. (For example,
+    // \Drupal\Component\Utility\Crypt::randomBytesBase64() would be vulnerable
+    // to this; the stage ID needs to be unique, but not cryptographically so.)
+    $id = (new Random())->name(32);
     // Re-acquire the tempstore to ensure that the lock is written by whoever is
     // actually logged in (or not) right now, since it's possible that the stage
     // was instantiated (i.e., __construct() was called) by a different session,
     // which would result in the lock having the wrong owner and the stage not
     // being claimable by whoever is actually creating it.
     $this->tempStore = $this->tempStoreFactory->get('package_manager_stage');
-    $this->tempStore->set(static::TEMPSTORE_LOCK_KEY, [$id, static::class]);
+    // For the lock value, we use both the stage's class and its type in order
+    // to prevent a stage from being manipulated by two different classes during
+    // a single life cycle.
+    $this->tempStore->set(static::TEMPSTORE_LOCK_KEY, [
+      $id,
+      static::class,
+      $this->getType(),
+    ]);
     $this->claim($id);
 
     $active_dir = $this->pathFactory->create($this->pathLocator->getProjectRoot());
     $stage_dir = $this->pathFactory->create($this->getStageDirectory());
 
-    $event = new PreCreateEvent($this, $this->getPathsToExclude());
+    $excluded_paths = $this->getPathsToExclude();
+    $event = new PreCreateEvent($this, $excluded_paths);
     // If an error occurs and we won't be able to create the stage, mark it as
     // available.
     $this->dispatch($event, [$this, 'markAsAvailable']);
 
     try {
-      $this->beginner->begin($active_dir, $stage_dir, new PathList(...$event->getExcludedPaths()), NULL, $timeout);
+      $this->beginner->begin($active_dir, $stage_dir, $excluded_paths, NULL, $timeout);
     }
     catch (\Throwable $error) {
       $this->destroy();
@@ -409,7 +456,7 @@ abstract class StageBase implements LoggerAwareInterface {
 
     // If constraints were changed, update those packages.
     if ($runtime || $dev) {
-      $command = array_merge(['update', '--with-all-dependencies'], $runtime, $dev);
+      $command = array_merge(['update', '--with-all-dependencies', '--optimize-autoloader'], $runtime, $dev);
       $do_stage($command);
     }
     $this->dispatch(new PostRequireEvent($this, $runtime, $dev));
@@ -442,23 +489,19 @@ abstract class StageBase implements LoggerAwareInterface {
     $active_dir = $this->pathFactory->create($this->pathLocator->getProjectRoot());
     $stage_dir = $this->pathFactory->create($this->getStageDirectory());
 
+    $excluded_paths = $this->getPathsToExclude();
+    $event = new PreApplyEvent($this, $excluded_paths);
     // If an error occurs while dispatching the events, ensure that ::destroy()
     // doesn't think we're in the middle of applying the staged changes to the
     // active directory.
-    $event = new PreApplyEvent($this, $this->getPathsToExclude());
     $this->tempStore->set(self::TEMPSTORE_APPLY_TIME_KEY, $this->time->getRequestTime());
     $this->dispatch($event, $this->setNotApplying(...));
 
     // Create a marker file so that we can tell later on if the commit failed.
     $this->failureMarker->write($this, $this->getFailureMarkerMessage());
-    // Exclude the failure file from the commit operation.
-    $paths_to_exclude = new PathList(...$event->getExcludedPaths());
-    $paths_to_exclude->add(
-      str_replace($this->pathLocator->getProjectRoot() . DIRECTORY_SEPARATOR, '', $this->failureMarker->getPath()),
-    );
 
     try {
-      $this->committer->commit($stage_dir, $active_dir, $paths_to_exclude, NULL, $timeout);
+      $this->committer->commit($stage_dir, $active_dir, $excluded_paths, NULL, $timeout);
     }
     catch (InvalidArgumentException | PreconditionException $e) {
       // The commit operation has not started yet, so we can clear the failure
@@ -536,26 +579,16 @@ abstract class StageBase implements LoggerAwareInterface {
       throw new StageException($this, 'Cannot destroy the stage directory while it is being applied to the active directory.');
     }
 
-    $this->dispatch(new PreDestroyEvent($this));
-    $staging_root = $this->getStagingRoot();
-    // If the stage root directory exists, delete it and everything in it.
-    if (file_exists($staging_root)) {
-      try {
-        $this->fileSystem->deleteRecursive($staging_root, function (string $path): void {
-          $this->fileSystem->chmod($path, 0777);
-        });
-      }
-      catch (FileException) {
-        // Deliberately swallow the exception so that the stage will be marked
-        // as available and the post-destroy event will be fired, even if the
-        // stage directory can't actually be deleted. The file system service
-        // logs the exception, so we don't need to do anything else here.
-      }
+    // If the stage directory exists, queue it to be automatically cleaned up
+    // later by a queue (which may or may not happen during cron).
+    // @see \Drupal\package_manager\Plugin\QueueWorker\Cleaner
+    if ($this->stageDirectoryExists()) {
+      $this->queueFactory->get('package_manager_cleanup')
+        ->createItem($this->getStageDirectory());
     }
 
     $this->storeDestroyInfo($force, $message);
     $this->markAsAvailable();
-    $this->dispatch(new PostDestroyEvent($this));
   }
 
   /**
@@ -595,6 +628,8 @@ abstract class StageBase implements LoggerAwareInterface {
     }
 
     if (isset($error)) {
+      // Ensure the error is logged for post-mortem diagnostics.
+      Error::logException($this->logger, $error);
       if ($on_error) {
         $on_error();
       }
@@ -648,7 +683,7 @@ abstract class StageBase implements LoggerAwareInterface {
       )->render());
     }
 
-    if ($stored_lock === [$unique_id, static::class]) {
+    if ($stored_lock === [$unique_id, static::class, $this->getType()]) {
       $this->lock = $stored_lock;
       return $this;
     }

package_manager/src/StatusCheckTrait.php

@@ -42,22 +42,12 @@ trait StatusCheckTrait {
     try {
       $paths_to_exclude_event = new CollectPathsToExcludeEvent($stage, $path_locator, $path_factory);
       $event_dispatcher->dispatch($paths_to_exclude_event);
-      $event = new StatusCheckEvent($stage, $paths_to_exclude_event->getAll());
     }
     catch (\Throwable $throwable) {
-      // We can dispatch the status check event without the paths to exclude,
-      // but it must be set explicitly to NULL, to allow those status checks to
-      // run that do not need the paths to exclude.
-      $event = new StatusCheckEvent($stage, NULL);
-      // Add the error that was encountered so that regardless of any other
-      // validation errors BaseRequirementsFulfilledValidator will stop the
-      // event propagation after the base requirement validators have run.
-      // @see \Drupal\package_manager\Validator\BaseRequirementsFulfilledValidator
-      $event->addErrorFromThrowable($throwable, t('Unable to collect the paths to exclude.'));
+      $paths_to_exclude_event = $throwable;
     }
-
-    $event_dispatcher->dispatch($event);
-    return $event->getResults();
+    $event = new StatusCheckEvent($stage, $paths_to_exclude_event);
+    return $event_dispatcher->dispatch($event)->getResults();
   }
 
 }

package_manager/src/TranslatableStringAdapter.php

@@ -36,7 +36,7 @@ final class TranslatableStringAdapter extends TranslatableMarkup implements Tran
   /**
    * {@inheritdoc}
    */
-  public function trans(TranslatorInterface $translator, ?string $locale = NULL): string {
+  public function trans(?TranslatorInterface $translator = NULL, ?string $locale = NULL): string {
     // This method is NEVER used by Drupal to translate the underlying string;
     // it exists solely for Composer Stager's translation system to
     // transparently translate Drupal strings using its own architecture.

package_manager/src/TranslatableStringFactory.php

@@ -9,7 +9,6 @@ use PhpTuf\ComposerStager\API\Translation\Factory\TranslatableFactoryInterface;
 use PhpTuf\ComposerStager\API\Translation\Service\DomainOptionsInterface;
 use PhpTuf\ComposerStager\API\Translation\Value\TranslatableInterface;
 use PhpTuf\ComposerStager\API\Translation\Value\TranslationParametersInterface;
-use PhpTuf\ComposerStager\Internal\Translation\Factory\TranslatableFactory as StagerTranslatableFactory;
 
 /**
  * Creates translatable strings that can interoperate with Composer Stager.
@@ -24,13 +23,13 @@ final class TranslatableStringFactory implements TranslatableFactoryInterface {
   /**
    * Constructs a TranslatableStringFactory object.
    *
-   * @param \PhpTuf\ComposerStager\Internal\Translation\Factory\TranslatableFactory $decorated
+   * @param \PhpTuf\ComposerStager\API\Translation\Factory\TranslatableFactoryInterface $decorated
    *   The decorated translatable factory service.
    * @param \Drupal\Core\StringTranslation\TranslationInterface $translation
    *   The string translation service.
    */
   public function __construct(
-    private readonly StagerTranslatableFactory $decorated,
+    private readonly TranslatableFactoryInterface $decorated,
     private readonly TranslationInterface $translation,
   ) {}
 

package_manager/src/Validator/ComposerPatchesValidator.php

@@ -4,6 +4,7 @@ declare(strict_types = 1);
 
 namespace Drupal\package_manager\Validator;
 
+use Composer\Semver\Semver;
 use Drupal\Component\Serialization\Json;
 use Drupal\Core\Extension\ModuleHandlerInterface;
 use Drupal\Core\StringTranslation\StringTranslationTrait;
@@ -155,15 +156,26 @@ final class ComposerPatchesValidator implements EventSubscriberInterface {
    */
   private function computePatcherStatus(string $working_dir): array {
     $list = $this->composerInspector->getInstalledPackagesList($working_dir);
-    $is_installed = isset($list[static::PLUGIN_NAME]);
+    $installed_version = $list[static::PLUGIN_NAME]?->version;
 
     $info = $this->composerInspector->getRootPackageInfo($working_dir);
     $is_root_requirement = array_key_exists(static::PLUGIN_NAME, $info['requires'] ?? []) || array_key_exists(static::PLUGIN_NAME, $info['devRequires'] ?? []);
 
-    $extra = Json::decode($this->composerInspector->getConfig('extra', $working_dir));
-    $exit_on_failure = $extra['composer-exit-on-patch-failure'] ?? FALSE;
+    // The 2.x version of the plugin always exits with an error if a patch can't
+    // be applied.
+    if ($installed_version && Semver::satisfies($installed_version, '^2')) {
+      $exit_on_failure = TRUE;
+    }
+    else {
+      $extra = Json::decode($this->composerInspector->getConfig('extra', $working_dir));
+      $exit_on_failure = $extra['composer-exit-on-patch-failure'] ?? FALSE;
+    }
 
-    return [$is_installed, $is_root_requirement, $exit_on_failure];
+    return [
+      is_string($installed_version),
+      $is_root_requirement,
+      $exit_on_failure,
+    ];
   }
 
   /**

package_manager/src/Validator/ComposerPluginsValidator.php

@@ -64,9 +64,10 @@ final class ComposerPluginsValidator implements EventSubscriberInterface {
   private const SUPPORTED_PLUGINS_THAT_DO_MODIFY = [
     // cSpell:disable
     // @see \Drupal\package_manager\Validator\ComposerPatchesValidator
-    'cweagans/composer-patches' => '^1.7.3',
+    'cweagans/composer-patches' => '^1.7.3 || ^2',
     // @see \Drupal\package_manager\PathExcluder\VendorHardeningExcluder
     'drupal/core-vendor-hardening' => '*',
+    'php-http/discovery' => '*',
     // cSpell:enable
   ];
 

package_manager/src/Validator/LockFileValidator.php

@@ -6,7 +6,7 @@ namespace Drupal\package_manager\Validator;
 
 use Drupal\Core\State\StateInterface;
 use Drupal\Core\StringTranslation\StringTranslationTrait;
-use Drupal\package_manager\Event\PostDestroyEvent;
+use Drupal\package_manager\Event\PostApplyEvent;
 use Drupal\package_manager\Event\PreApplyEvent;
 use Drupal\package_manager\Event\PreCreateEvent;
 use Drupal\package_manager\Event\PreOperationStageEvent;
@@ -176,7 +176,7 @@ final class LockFileValidator implements EventSubscriberInterface {
       PreRequireEvent::class => 'validate',
       PreApplyEvent::class => 'validate',
       StatusCheckEvent::class => 'validate',
-      PostDestroyEvent::class => 'deleteHash',
+      PostApplyEvent::class => 'deleteHash',
     ];
   }
 

package_manager/src/Validator/PhpExtensionsValidator.php

@@ -6,6 +6,9 @@ namespace Drupal\package_manager\Validator;
 
 use Drupal\Component\FileSystem\FileSystem as DrupalFilesystem;
 use Drupal\Core\StringTranslation\StringTranslationTrait;
+use Drupal\package_manager\Event\PreApplyEvent;
+use Drupal\package_manager\Event\PreCreateEvent;
+use Drupal\package_manager\Event\PreOperationStageEvent;
 use Drupal\package_manager\Event\StatusCheckEvent;
 use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 
@@ -59,17 +62,17 @@ class PhpExtensionsValidator implements EventSubscriberInterface {
   }
 
   /**
-   * Flags a warning if the OpenSSL extension is not installed.
+   * Flags an error if the OpenSSL extension is not installed.
    *
-   * @param \Drupal\package_manager\Event\StatusCheckEvent $event
+   * @param \Drupal\package_manager\Event\PreOperationStageEvent $event
    *   The event object.
    */
-  public function validateOpenSsl(StatusCheckEvent $event): void {
+  public function validateOpenSsl(PreOperationStageEvent $event): void {
     if (!$this->isExtensionLoaded('openssl')) {
       $message = $this->t('The OpenSSL extension is not enabled, which is a security risk. See <a href=":url">the PHP documentation</a> for information on how to enable this extension.', [
         ':url' => 'https://www.php.net/manual/en/openssl.installation.php',
       ]);
-      $event->addWarning([$message]);
+      $event->addError([$message]);
     }
   }
 
@@ -97,6 +100,8 @@ class PhpExtensionsValidator implements EventSubscriberInterface {
         ['validateXdebug'],
         ['validateOpenSsl'],
       ],
+      PreCreateEvent::class => ['validateOpenSsl'],
+      PreApplyEvent::class => ['validateOpenSsl'],
     ];
   }
 

package_manager/src/Validator/PhpTufValidator.php

@@ -59,11 +59,15 @@ final class PhpTufValidator implements EventSubscriberInterface {
    *   The Composer inspector service.
    * @param \Drupal\Core\Extension\ModuleHandlerInterface $moduleHandler
    *   The module handler service.
+   * @param string $baseUrl
+   *   The base URL of the repository, or repositories, defined in
+   *   `composer.json`that must be protected by TUF.
    */
   public function __construct(
     private readonly PathLocator $pathLocator,
     private readonly ComposerInspector $composerInspector,
-    private readonly ModuleHandlerInterface $moduleHandler
+    private readonly ModuleHandlerInterface $moduleHandler,
+    private readonly string $baseUrl,
   ) {}
 
   /**
@@ -147,13 +151,12 @@ final class PhpTufValidator implements EventSubscriberInterface {
       $messages[] = $message;
     }
 
-    // Get the defined repositories that use packages.drupal.org.
+    // Get the defined repositories that live at the base URL, and confirm that
+    // they have all opted into TUF protection.
     $repositories = array_filter(
       Json::decode($this->composerInspector->getConfig('repositories', $dir)),
-      fn (array $r): bool => str_starts_with($r['url'], 'https://packages.drupal.org')
+      fn (array $r): bool => str_starts_with($r['url'], $this->baseUrl)
     );
-
-    // All packages.drupal.org repositories must have TUF protection.
     foreach ($repositories as $repository) {
       if (empty($repository['tuf'])) {
         $messages[] = $this->t('TUF is not enabled for the @url repository.', [
@@ -162,10 +165,11 @@ final class PhpTufValidator implements EventSubscriberInterface {
       }
     }
 
-    // There must be at least one repository using packages.drupal.org, since
-    // that's the only repository which supports TUF right now.
+    // There must be at least one repository using the base URL.
     if (empty($repositories)) {
-      $message = $this->t('The <code>https://packages.drupal.org</code> Composer repository must be defined in <code>composer.json</code>.');
+      $message = $this->t('The <code>@url</code> Composer repository must be defined in <code>composer.json</code>.', [
+        '@url' => $this->baseUrl,
+      ]);
       if (isset($help_url)) {
         $message = $this->t('@message See <a href=":url">the help page</a> for more information on how to set up this repository.', [
           '@message' => $message,

package_manager/src/Validator/RsyncValidator.php

@@ -72,7 +72,7 @@ final class RsyncValidator implements EventSubscriberInterface {
     if ($configured_syncer === 'php') {
       // Only status checks support warnings.
       if ($event instanceof StatusCheckEvent) {
-        $message = $this->t('You are currently using the PHP file syncer, which has known problems and is not stable. It is strongly recommended to switch back to the default <em>rsync</em> file syncer instead.');
+        $message = $this->t('You are currently using the PHP file syncer, which has known problems and is not stable. <strong>The PHP file syncer will be removed in Package Manager 3.1.0.</strong> Switch back to the default <em>rsync</em> file syncer to continue using Package Manager.');
 
         if (!$rsync_found) {
           $message = $this->t('@message <code>rsync</code> was not found on your system.', ['@message' => $message]);

package_manager/src/Validator/SupportedReleaseValidator.php

@@ -121,12 +121,16 @@ final class SupportedReleaseValidator implements EventSubscriberInterface {
       $event->addError($unsupported_packages, $summary);
     }
     if ($unknown_packages) {
-      $summary = $this->formatPlural(
-        count($unknown_packages),
-        'Cannot update because the following new or updated Drupal package does not have project information.',
-        'Cannot update because the following new or updated Drupal packages do not have project information.',
-      );
-      $event->addError($unknown_packages, $summary);
+      $event->addError([
+        $this->formatPlural(
+          count($unknown_packages),
+          'Cannot update because the following new or updated Drupal package does not have project information: @unknown_packages',
+          'Cannot update because the following new or updated Drupal packages do not have project information: @unknown_packages',
+          [
+            '@unknown_packages' => implode(', ', $unknown_packages),
+          ],
+        ),
+      ]);
     }
   }
 

package_manager/src/Validator/SymlinkValidator.php

@@ -9,7 +9,7 @@ use Drupal\package_manager\Event\PreRequireEvent;
 use Drupal\package_manager\PathLocator;
 use PhpTuf\ComposerStager\API\Exception\PreconditionException;
 use PhpTuf\ComposerStager\API\Path\Factory\PathFactoryInterface;
-use PhpTuf\ComposerStager\API\Path\Value\PathList;
+use PhpTuf\ComposerStager\API\Path\Factory\PathListFactoryInterface;
 use PhpTuf\ComposerStager\API\Precondition\Service\NoUnsupportedLinksExistInterface;
 use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 
@@ -36,11 +36,14 @@ final class SymlinkValidator implements EventSubscriberInterface {
    *   The Composer Stager precondition that this validator wraps.
    * @param \PhpTuf\ComposerStager\API\Path\Factory\PathFactoryInterface $pathFactory
    *   The path factory service.
+   * @param \PhpTuf\ComposerStager\API\Path\Factory\PathListFactoryInterface $pathListFactory
+   *   The path list factory service.
    */
   public function __construct(
     private readonly PathLocator $pathLocator,
     private readonly NoUnsupportedLinksExistInterface $precondition,
     private readonly PathFactoryInterface $pathFactory,
+    private readonly PathListFactoryInterface $pathListFactory,
   ) {}
 
   /**
@@ -65,17 +68,20 @@ final class SymlinkValidator implements EventSubscriberInterface {
     }
     $stage_dir = $this->pathFactory->create($stage_dir);
 
-    $excluded_paths = $event->getExcludedPaths();
     // Return early if no excluded paths were collected because this validator
     // is dependent on knowing which paths to exclude when searching for
     // symlinks.
     // @see \Drupal\package_manager\StatusCheckTrait::runStatusCheck()
-    if ($excluded_paths === NULL) {
+    if ($event->excludedPaths === NULL) {
       return;
     }
 
+    // The list of excluded paths is immutable, but the precondition may need to
+    // mutate it, so convert it back to a normal, mutable path list.
+    $exclusions = $this->pathListFactory->create(...$event->excludedPaths->getAll());
+
     try {
-      $this->precondition->assertIsFulfilled($active_dir, $stage_dir, new PathList(...$excluded_paths));
+      $this->precondition->assertIsFulfilled($active_dir, $stage_dir, $exclusions);
     }
     catch (PreconditionException $e) {
       $event->addErrorFromThrowable($e);

package_manager/tests/fixtures/build_test_projects/main_module/composer.json

+{
+  "name": "drupal/main_module",
+  "type": "drupal-module",
+  "version": "1.0.0"
+}

package_manager/tests/fixtures/build_test_projects/main_module/main_module.info.yml.hide

+name: Main module
+type: module
+core_version_requirement: ^9 || ^10
+project: main_module
+

package_manager/tests/fixtures/build_test_projects/main_module/main_module_submodule/main_module_submodule.info.yml.hide

+name: Main Module Submodule
+type: module
+core_version_requirement: ^9 || ^10
+project: main_module