package_manager/src/Event/PreCreateEvent.php

 <?php
 
+declare(strict_types = 1);
+
 namespace Drupal\package_manager\Event;
 
+use Drupal\package_manager\ImmutablePathList;
+use Drupal\package_manager\StageBase;
+use PhpTuf\ComposerStager\API\Path\Value\PathListInterface;
+
 /**
- * Event fired before a staging area is created.
+ * Event fired before a stage directory is created.
  */
-class PreCreateEvent extends PreOperationStageEvent {
+final class PreCreateEvent extends PreOperationStageEvent {
+
+  /**
+   * The list of paths to exclude from the stage directory.
+   *
+   * @var \Drupal\package_manager\ImmutablePathList
+   */
+  public readonly ImmutablePathList $excludedPaths;
 
-  use ExcludedPathsTrait;
+  /**
+   * Constructs a PreCreateEvent object.
+   *
+   * @param \Drupal\package_manager\StageBase $stage
+   *   The stage which fired this event.
+   * @param \PhpTuf\ComposerStager\API\Path\Value\PathListInterface $excluded_paths
+   *   The list of paths to exclude. These will not be copied into the stage
+   *   directory when it is created.
+   */
+  public function __construct(StageBase $stage, PathListInterface $excluded_paths) {
+    parent::__construct($stage);
+    $this->excludedPaths = new ImmutablePathList($excluded_paths);
+  }
 
 }

package_manager/src/Event/PreDestroyEvent.php

-<?php
-
-namespace Drupal\package_manager\Event;
-
-/**
- * Event fired before the staging area is destroyed.
- *
- * If the stage is being force destroyed, ::getStage() may return an object of a
- * different class than the one that originally created the staging area.
- *
- * @see \Drupal\package_manager\Stage::destroy()
- */
-class PreDestroyEvent extends PreOperationStageEvent {
-}

package_manager/src/Event/PreOperationStageEvent.php

 <?php
 
+declare(strict_types = 1);
+
 namespace Drupal\package_manager\Event;
 
 use Drupal\Core\StringTranslation\TranslatableMarkup;
 use Drupal\package_manager\ValidationResult;
+use Drupal\system\SystemManager;
 
 /**
  * Base class for events dispatched before a stage life cycle operation.
@@ -30,17 +33,62 @@ abstract class PreOperationStageEvent extends StageEvent {
   public function getResults(?int $severity = NULL): array {
     if ($severity !== NULL) {
       return array_filter($this->results, function ($result) use ($severity) {
-        return $result->getSeverity() === $severity;
+        return $result->severity === $severity;
       });
     }
     return $this->results;
   }
 
   /**
-   * Adds error information to the event.
+   * Convenience method, adds error validation result.
+   *
+   * @param \Drupal\Core\StringTranslation\TranslatableMarkup[] $messages
+   *   The error messages.
+   * @param \Drupal\Core\StringTranslation\TranslatableMarkup|null $summary
+   *   (optional) The summary of error messages. Only required if there
+   *   is more than one message.
    */
   public function addError(array $messages, ?TranslatableMarkup $summary = NULL): void {
-    $this->results[] = ValidationResult::createError($messages, $summary);
+    $this->addResult(ValidationResult::createError(array_values($messages), $summary));
+  }
+
+  /**
+   * Convenience method, adds an error validation result from a throwable.
+   *
+   * @param \Throwable $throwable
+   *   The throwable.
+   * @param \Drupal\Core\StringTranslation\TranslatableMarkup|null $summary
+   *   (optional) The summary of error messages.
+   */
+  public function addErrorFromThrowable(\Throwable $throwable, ?TranslatableMarkup $summary = NULL): void {
+    $this->addResult(ValidationResult::createErrorFromThrowable($throwable, $summary));
+  }
+
+  /**
+   * Adds a validation result to the event.
+   *
+   * @param \Drupal\package_manager\ValidationResult $result
+   *   The validation result to add.
+   *
+   * @throws \InvalidArgumentException
+   *   Thrown if the validation result is not an error.
+   */
+  public function addResult(ValidationResult $result): void {
+    // Only errors are allowed for this event.
+    if ($result->severity !== SystemManager::REQUIREMENT_ERROR) {
+      throw new \InvalidArgumentException('Only errors are allowed.');
+    }
+    $this->results[] = $result;
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function stopPropagation(): void {
+    if (empty($this->getResults(SystemManager::REQUIREMENT_ERROR))) {
+      $this->addErrorFromThrowable(new \LogicException('Event propagation stopped without any errors added to the event. This bypasses the package_manager validation system.'));
+    }
+    parent::stopPropagation();
   }
 
 }

package_manager/src/Event/PreRequireEvent.php

 <?php
 
+declare(strict_types = 1);
+
 namespace Drupal\package_manager\Event;
 
 /**
- * Event fired before packages are updated to the staging area.
+ * Event fired before packages are updated to the stage directory.
  */
-class PreRequireEvent extends PreOperationStageEvent {
+final class PreRequireEvent extends PreOperationStageEvent {
+
+  use RequireEventTrait;
+
 }

package_manager/src/Event/RequireEventTrait.php

+<?php
+
+declare(strict_types = 1);
+
+namespace Drupal\package_manager\Event;
+
+use Drupal\package_manager\StageBase;
+
+/**
+ * Common methods for pre- and post-require events.
+ *
+ * @internal
+ *   This is an internal part of Automatic Updates and should only be used by
+ *   \Drupal\package_manager\Event\PreRequireEvent and
+ *   \Drupal\package_manager\Event\PostRequireEvent.
+ */
+trait RequireEventTrait {
+
+  /**
+   * The runtime packages, in the form 'vendor/name:constraint'.
+   *
+   * @var string[]
+   */
+  private $runtimePackages;
+
+  /**
+   * The dev packages to be required, in the form 'vendor/name:constraint'.
+   *
+   * @var string[]
+   */
+  private $devPackages;
+
+  /**
+   * Constructs the object.
+   *
+   * @param \Drupal\package_manager\StageBase $stage
+   *   The stage.
+   * @param string[] $runtime_packages
+   *   The runtime (i.e., non-dev) packages to be required, in the form
+   *   'vendor/name:constraint'.
+   * @param string[] $dev_packages
+   *   The dev packages to be required, in the form 'vendor/name:constraint'.
+   */
+  public function __construct(StageBase $stage, array $runtime_packages, array $dev_packages = []) {
+    $this->runtimePackages = $runtime_packages;
+    $this->devPackages = $dev_packages;
+    parent::__construct($stage);
+  }
+
+  /**
+   * Gets the runtime (i.e., non-dev) packages.
+   *
+   * @return string[]
+   *   An array of packages where the values are version constraints and keys
+   *   are package names in the form `vendor/name`. Packages without a version
+   *   constraint will default to `*`.
+   */
+  public function getRuntimePackages(): array {
+    return $this->getKeyedPackages($this->runtimePackages);
+  }
+
+  /**
+   * Gets the dev packages.
+   *
+   * @return string[]
+   *   An array of packages where the values are version constraints and keys
+   *   are package names in the form `vendor/name`. Packages without a version
+   *   constraint will default to `*`.
+   */
+  public function getDevPackages(): array {
+    return $this->getKeyedPackages($this->devPackages);
+  }
+
+  /**
+   * Gets packages as a keyed array.
+   *
+   * @param string[] $packages
+   *   The packages, in the form 'vendor/name:version'.
+   *
+   * @return string[]
+   *   An array of packages where the values are version constraints and keys
+   *   are package names in the form `vendor/name`. Packages without a version
+   *   constraint will default to `*`.
+   */
+  private function getKeyedPackages(array $packages): array {
+    $keyed_packages = [];
+    foreach ($packages as $package) {
+      if (strpos($package, ':') > 0) {
+        [$name, $constraint] = explode(':', $package);
+      }
+      else {
+        [$name, $constraint] = [$package, '*'];
+      }
+      $keyed_packages[$name] = $constraint;
+    }
+    return $keyed_packages;
+  }
+
+}

package_manager/src/Event/StageEvent.php

 <?php
 
+declare(strict_types = 1);
+
 namespace Drupal\package_manager\Event;
 
-use Drupal\package_manager\Stage;
+use Drupal\package_manager\StageBase;
 use Symfony\Contracts\EventDispatcher\Event;
 
 /**
- * Base class for all events related to the life cycle of the staging area.
+ * Base class for all events related to the life cycle of the stage.
  */
 abstract class StageEvent extends Event {
 
-  /**
-   * The stage which fired this event.
-   *
-   * @var \Drupal\package_manager\Stage
-   */
-  protected $stage;
-
   /**
    * Constructs a StageEvent object.
    *
-   * @param \Drupal\package_manager\Stage $stage
-   *   The stage which fired this event.
-   */
-  public function __construct(Stage $stage) {
-    $this->stage = $stage;
-  }
-
-  /**
-   * Returns the stage which fired this event.
-   *
-   * @return \Drupal\package_manager\Stage
+   * @param \Drupal\package_manager\StageBase $stage
    *   The stage which fired this event.
    */
-  public function getStage(): Stage {
-    return $this->stage;
+  public function __construct(public readonly StageBase $stage) {
   }
 
 }

package_manager/src/Event/StatusCheckEvent.php

+<?php
+
+declare(strict_types = 1);
+
+namespace Drupal\package_manager\Event;
+
+use Drupal\Core\StringTranslation\TranslatableMarkup;
+use Drupal\package_manager\ImmutablePathList;
+use Drupal\package_manager\StageBase;
+use Drupal\package_manager\ValidationResult;
+use PhpTuf\ComposerStager\API\Path\Value\PathListInterface;
+
+/**
+ * Event fired to check the status of the system to use Package Manager.
+ *
+ * The event's stage will be set with the type of stage that will perform the
+ * operations. The stage may or may not be currently in use.
+ */
+final class StatusCheckEvent extends PreOperationStageEvent {
+
+  /**
+   * The paths to exclude, or NULL if there was an error collecting them.
+   *
+   * @var \Drupal\package_manager\ImmutablePathList|null
+   *
+   * @see ::__construct()
+   */
+  public readonly ?ImmutablePathList $excludedPaths;
+
+  /**
+   * Constructs a StatusCheckEvent object.
+   *
+   * @param \Drupal\package_manager\StageBase $stage
+   *   The stage which fired this event.
+   * @param \PhpTuf\ComposerStager\API\Path\Value\PathListInterface|\Throwable $excluded_paths
+   *   The list of paths to exclude or, if an error occurred while they were
+   *   being collected, the throwable from that error. If this is a throwable,
+   *   it will be converted to a validation error.
+   */
+  public function __construct(StageBase $stage, PathListInterface|\Throwable $excluded_paths) {
+    parent::__construct($stage);
+
+    // If there was an error collecting the excluded paths, convert it to a
+    // validation error so we can still run status checks that don't need to
+    // examine the list of excluded paths.
+    if ($excluded_paths instanceof \Throwable) {
+      $this->addErrorFromThrowable($excluded_paths);
+      $excluded_paths = NULL;
+    }
+    else {
+      $excluded_paths = new ImmutablePathList($excluded_paths);
+    }
+    $this->excludedPaths = $excluded_paths;
+  }
+
+  /**
+   * Adds warning information to the event.
+   *
+   * @param \Drupal\Core\StringTranslation\TranslatableMarkup[] $messages
+   *   One or more warning messages.
+   * @param \Drupal\Core\StringTranslation\TranslatableMarkup|null $summary
+   *   A summary of warning messages. Required if there is more than one
+   *   message, optional otherwise.
+   */
+  public function addWarning(array $messages, ?TranslatableMarkup $summary = NULL): void {
+    $this->addResult(ValidationResult::createWarning($messages, $summary));
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function addResult(ValidationResult $result): void {
+    // Override the parent to also allow warnings.
+    $this->results[] = $result;
+  }
+
+}

package_manager/src/EventSubscriber/ChangeLogger.php

+<?php
+
+declare(strict_types = 1);
+
+namespace Drupal\package_manager\EventSubscriber;
+
+use Drupal\Core\StringTranslation\StringTranslationTrait;
+use Drupal\package_manager\Event\PostApplyEvent;
+use Drupal\package_manager\Event\PostRequireEvent;
+use Drupal\package_manager\ComposerInspector;
+use Drupal\package_manager\Event\PreCreateEvent;
+use Drupal\package_manager\PathLocator;
+use Psr\Log\LoggerAwareInterface;
+use Psr\Log\LoggerAwareTrait;
+use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+
+/**
+ * Event subscriber to log changes that happen during the stage life cycle.
+ *
+ * @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 ChangeLogger implements EventSubscriberInterface, LoggerAwareInterface {
+
+  use LoggerAwareTrait;
+  use StringTranslationTrait;
+
+  /**
+   * The metadata key under which to store the installed packages at start.
+   *
+   * @var string
+   *
+   * @see ::recordInstalledPackages()
+   */
+  private const INSTALLED_PACKAGES_KEY = 'package_manager_installed_packages';
+
+  /**
+   * The metadata key under which to store the requested package versions.
+   *
+   * @var string
+   *
+   * @see ::recordRequestedPackageVersions()
+   */
+  private const REQUESTED_PACKAGES_KEY = 'package_manager_requested_packages';
+
+  /**
+   * Constructs a ChangeLogger object.
+   *
+   * @param \Drupal\package_manager\ComposerInspector $composerInspector
+   *   The Composer inspector service.
+   * @param \Drupal\package_manager\PathLocator $pathLocator
+   *   The path locator service.
+   */
+  public function __construct(
+    private readonly ComposerInspector $composerInspector,
+    private readonly PathLocator $pathLocator,
+  ) {}
+
+  /**
+   * Records packages installed in the project root.
+   *
+   * We need to do this before the stage has been created, so that we have a
+   * complete picture of which requested packages are merely being updated, and
+   * which are being newly added. Once the stage has been created, the installed
+   * packages won't change -- if they do, a validation error will be raised.
+   *
+   * @param \Drupal\package_manager\Event\PreCreateEvent $event
+   *   The event being handled.
+   *
+   * @see \Drupal\package_manager\Validator\LockFileValidator
+   */
+  public function recordInstalledPackages(PreCreateEvent $event): void {
+    $packages = $this->composerInspector->getInstalledPackagesList($this->pathLocator->getProjectRoot());
+    $event->stage->setMetadata(static::INSTALLED_PACKAGES_KEY, $packages);
+  }
+
+  /**
+   * Records requested packages.
+   *
+   * @param \Drupal\package_manager\Event\PostRequireEvent $event
+   *   The event object.
+   */
+  public function recordRequestedPackageVersions(PostRequireEvent $event): void {
+    // There could be multiple require operations, so overlay the requested
+    // packages from the current operation onto the requested packages from any
+    // previous require operation.
+    $requested_packages = array_merge(
+      $event->stage->getMetadata(static::REQUESTED_PACKAGES_KEY) ?? [],
+      $event->getRuntimePackages(),
+      $event->getDevPackages(),
+    );
+    $event->stage->setMetadata(static::REQUESTED_PACKAGES_KEY, $requested_packages);
+  }
+
+  /**
+   * Logs all Package Manager changes.
+   *
+   * @param \Drupal\package_manager\Event\PostApplyEvent $event
+   *   The event being handled.
+   */
+  public function logChanges(PostApplyEvent $event): void {
+    $installed_at_start = $event->stage->getMetadata(static::INSTALLED_PACKAGES_KEY);
+    $installed_post_apply = $this->composerInspector->getInstalledPackagesList($this->pathLocator->getProjectRoot());
+
+    // Compare the packages which were installed when the stage was created
+    // against the package versions that were requested over all of the stage's
+    // require operations, and create a log entry listing all of it.
+    $requested_log = [];
+
+    $requested_packages = $event->stage->getMetadata(static::REQUESTED_PACKAGES_KEY) ?? [];
+    // Sort the requested packages by name, to make it easier to review a large
+    // change list.
+    ksort($requested_packages, SORT_NATURAL);
+    foreach ($requested_packages as $name => $constraint) {
+      $installed_version = $installed_at_start[$name]?->version;
+      if ($installed_version === NULL) {
+        // For clarity, make the "any version" constraint human-readable.
+        if ($constraint === '*') {
+          $constraint = $this->t('* (any version)');
+        }
+        $requested_log[] = $this->t('- Install @name @constraint', [
+          '@name' => $name,
+          '@constraint' => $constraint,
+        ]);
+      }
+      else {
+        $requested_log[] = $this->t('- Update @name from @installed_version to @constraint', [
+          '@name' => $name,
+          '@installed_version' => $installed_version,
+          '@constraint' => $constraint,
+        ]);
+      }
+    }
+    // It's possible that $requested_log will be empty -- for example, a custom
+    // stage that only does removals, or some other operation, and never
+    // dispatches PostRequireEvent.
+    if ($requested_log) {
+      $message = $this->t("Requested changes:\n@change_list", [
+        '@change_list' => implode("\n", array_map('strval', $requested_log)),
+      ]);
+      $this->logger->info($message);
+    }
+
+    // Create a separate log entry listing everything that actually changed.
+    $applied_log = [];
+
+    $updated_packages = $installed_post_apply->getPackagesWithDifferentVersionsIn($installed_at_start);
+    // Sort the packages by name to make it easier to review large change sets.
+    $updated_packages->ksort(SORT_NATURAL);
+    foreach ($updated_packages as $name => $package) {
+      $applied_log[] = $this->t('- Updated @name from @installed_version to @updated_version', [
+        '@name' => $name,
+        '@installed_version' => $installed_at_start[$name]->version,
+        '@updated_version' => $package->version,
+      ]);
+    }
+
+    $added_packages = $installed_post_apply->getPackagesNotIn($installed_at_start);
+    $added_packages->ksort(SORT_NATURAL);
+    foreach ($added_packages as $name => $package) {
+      $applied_log[] = $this->t('- Installed @name @version', [
+        '@name' => $name,
+        '@version' => $package->version,
+      ]);
+    }
+
+    $removed_packages = $installed_at_start->getPackagesNotIn($installed_post_apply);
+    $removed_packages->ksort(SORT_NATURAL);
+    foreach ($installed_at_start->getPackagesNotIn($installed_post_apply) as $name => $package) {
+      $applied_log[] = $this->t('- Uninstalled @name', ['@name' => $name]);
+    }
+    $message = $this->t("Applied changes:\n@change_list", [
+      '@change_list' => implode("\n", array_map('strval', $applied_log)),
+    ]);
+    $this->logger->info($message);
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public static function getSubscribedEvents(): array {
+    return [
+      PreCreateEvent::class => ['recordInstalledPackages'],
+      PostRequireEvent::class => ['recordRequestedPackageVersions'],
+      PostApplyEvent::class => ['logChanges'],
+    ];
+  }
+
+}

package_manager/src/EventSubscriber/ExcludedPathsSubscriber.php

-<?php
-
-namespace Drupal\package_manager\EventSubscriber;
-
-use Drupal\Core\Database\Connection;
-use Drupal\Core\StreamWrapper\LocalStream;
-use Drupal\Core\StreamWrapper\StreamWrapperManagerInterface;
-use Drupal\package_manager\Event\PreApplyEvent;
-use Drupal\package_manager\Event\PreCreateEvent;
-use Drupal\package_manager\Event\StageEvent;
-use Drupal\package_manager\PathLocator;
-use Symfony\Component\EventDispatcher\EventSubscriberInterface;
-use Symfony\Component\Filesystem\Filesystem;
-use Symfony\Component\Finder\Finder;
-
-/**
- * Defines an event subscriber to exclude certain paths from staging areas.
- */
-class ExcludedPathsSubscriber implements EventSubscriberInterface {
-
-  /**
-   * The current site path, relative to the Drupal root.
-   *
-   * @var string
-   */
-  protected $sitePath;
-
-  /**
-   * The Symfony file system service.
-   *
-   * @var \Symfony\Component\Filesystem\Filesystem
-   */
-  protected $fileSystem;
-
-  /**
-   * The stream wrapper manager service.
-   *
-   * @var \Drupal\Core\StreamWrapper\StreamWrapperManagerInterface
-   */
-  protected $streamWrapperManager;
-
-  /**
-   * The database connection.
-   *
-   * @var \Drupal\Core\Database\Connection
-   */
-  protected $database;
-
-  /**
-   * The path locator service.
-   *
-   * @var \Drupal\package_manager\PathLocator
-   */
-  protected $pathLocator;
-
-  /**
-   * Constructs an ExcludedPathsSubscriber.
-   *
-   * @param string $site_path
-   *   The current site path, relative to the Drupal root.
-   * @param \Symfony\Component\Filesystem\Filesystem $file_system
-   *   The Symfony file system service.
-   * @param \Drupal\Core\StreamWrapper\StreamWrapperManagerInterface $stream_wrapper_manager
-   *   The stream wrapper manager service.
-   * @param \Drupal\Core\Database\Connection $database
-   *   The database connection.
-   * @param \Drupal\package_manager\PathLocator $path_locator
-   *   The path locator service.
-   */
-  public function __construct(string $site_path, Filesystem $file_system, StreamWrapperManagerInterface $stream_wrapper_manager, Connection $database, PathLocator $path_locator) {
-    $this->sitePath = $site_path;
-    $this->fileSystem = $file_system;
-    $this->streamWrapperManager = $stream_wrapper_manager;
-    $this->database = $database;
-    $this->pathLocator = $path_locator;
-  }
-
-  /**
-   * Flags paths to be excluded, relative to the web root.
-   *
-   * This should only be used for paths that, if they exist at all, are
-   * *guaranteed* to exist within the web root.
-   *
-   * @param \Drupal\package_manager\Event\PreCreateEvent|\Drupal\package_manager\Event\PreApplyEvent $event
-   *   The event object.
-   * @param string[] $paths
-   *   The paths to exclude. These should be relative to the web root, and will
-   *   be made relative to the project root.
-   */
-  protected function excludeInWebRoot(StageEvent $event, array $paths): void {
-    $web_root = $this->pathLocator->getWebRoot();
-    if ($web_root) {
-      $web_root .= '/';
-    }
-
-    foreach ($paths as $path) {
-      // Make the path relative to the project root by prefixing the web root.
-      $event->excludePath($web_root . $path);
-    }
-  }
-
-  /**
-   * Flags paths to be excluded, relative to the project root.
-   *
-   * @param \Drupal\package_manager\Event\PreCreateEvent|\Drupal\package_manager\Event\PreApplyEvent $event
-   *   The event object.
-   * @param string[] $paths
-   *   The paths to exclude. Absolute paths will be made relative to the project
-   *   root; relative paths will be assumed to already be relative to the
-   *   project root, and excluded as given.
-   */
-  protected function excludeInProjectRoot(StageEvent $event, array $paths): void {
-    $project_root = $this->pathLocator->getProjectRoot();
-
-    foreach ($paths as $path) {
-      // Make absolute paths relative to the project root.
-      $path = str_replace($project_root, NULL, $path);
-      $path = ltrim($path, '/');
-      $event->excludePath($path);
-    }
-  }
-
-  /**
-   * Excludes common paths from staging operations.
-   *
-   * @param \Drupal\package_manager\Event\PreApplyEvent|\Drupal\package_manager\Event\PreCreateEvent $event
-   *   The event object.
-   *
-   * @see \Drupal\package_manager\Event\ExcludedPathsTrait::excludePath()
-   */
-  public function ignoreCommonPaths(StageEvent $event): void {
-    // Compile two lists of paths to exclude: paths that are relative to the
-    // project root, and paths that are relative to the web root.
-    $web = $project = [];
-
-    // Always ignore automated test directories. If they exist, they will be in
-    // the web root.
-    $web[] = 'sites/simpletest';
-
-    // If the core-vendor-hardening plugin (used in the legacy-project template)
-    // is present, it may have written security hardening files in the vendor
-    // directory. They should always be ignored.
-    $vendor_dir = $this->pathLocator->getVendorDirectory();
-    $project[] = $vendor_dir . '/web.config';
-    $project[] = $vendor_dir . '/.htaccess';
-
-    // Ignore public and private files. These paths could be either absolute or
-    // relative, depending on site settings. If they are absolute, treat them
-    // as relative to the project root. Otherwise, treat them as relative to
-    // the web root.
-    $files = array_filter([
-      $this->getFilesPath('public'),
-      $this->getFilesPath('private'),
-    ]);
-    foreach ($files as $path) {
-      if ($this->fileSystem->isAbsolutePath($path)) {
-        $project[] = $path;
-      }
-      else {
-        $web[] = $path;
-      }
-    }
-
-    // Ignore site-specific settings files, which are always in the web root.
-    $settings_files = [
-      'settings.php',
-      'settings.local.php',
-      'services.yml',
-    ];
-    foreach ($settings_files as $settings_file) {
-      $web[] = $this->sitePath . '/' . $settings_file;
-      $web[] = 'sites/default/' . $settings_file;
-    }
-
-    // If the database is SQLite, it might be located in the active directory
-    // and we should ignore it. Always treat it as relative to the project root.
-    if ($this->database->driver() === 'sqlite') {
-      $options = $this->database->getConnectionOptions();
-      $project[] = $options['database'];
-      $project[] = $options['database'] . '-shm';
-      $project[] = $options['database'] . '-wal';
-    }
-
-    // Find all .git directories in the project and exclude them. We cannot do
-    // this with FileSystemInterface::scanDirectory() because it unconditionally
-    // excludes anything starting with a dot.
-    $finder = Finder::create()
-      ->in($this->pathLocator->getProjectRoot())
-      ->directories()
-      ->name('.git')
-      ->ignoreVCS(FALSE)
-      ->ignoreDotFiles(FALSE)
-      ->ignoreUnreadableDirs();
-
-    foreach ($finder as $git_directory) {
-      $project[] = $git_directory->getPathname();
-    }
-
-    $this->excludeInWebRoot($event, $web);
-    $this->excludeInProjectRoot($event, $project);
-  }
-
-  /**
-   * Reacts before staged changes are committed the active directory.
-   *
-   * @param \Drupal\package_manager\Event\PreApplyEvent $event
-   *   The event object.
-   */
-  public function preApply(PreApplyEvent $event): void {
-    // Don't copy anything from the staging area's sites/default.
-    // @todo Make this a lot smarter in https://www.drupal.org/i/3228955.
-    $this->excludeInWebRoot($event, ['sites/default']);
-
-    $this->ignoreCommonPaths($event);
-  }
-
-  /**
-   * Returns the storage path for a stream wrapper.
-   *
-   * This will only work for stream wrappers that extend
-   * \Drupal\Core\StreamWrapper\LocalStream, which includes the stream wrappers
-   * for public and private files.
-   *
-   * @param string $scheme
-   *   The stream wrapper scheme.
-   *
-   * @return string|null
-   *   The storage path for files using the given scheme, relative to the Drupal
-   *   root, or NULL if the stream wrapper does not extend
-   *   \Drupal\Core\StreamWrapper\LocalStream.
-   */
-  private function getFilesPath(string $scheme): ?string {
-    $wrapper = $this->streamWrapperManager->getViaScheme($scheme);
-    if ($wrapper instanceof LocalStream) {
-      return $wrapper->getDirectoryPath();
-    }
-    return NULL;
-  }
-
-  /**
-   * {@inheritdoc}
-   */
-  public static function getSubscribedEvents() {
-    return [
-      PreCreateEvent::class => 'ignoreCommonPaths',
-      PreApplyEvent::class => 'preApply',
-    ];
-  }
-
-}

package_manager/src/EventSubscriber/UpdateDataSubscriber.php

 <?php
 
+declare(strict_types = 1);
+
 namespace Drupal\package_manager\EventSubscriber;
 
 use Drupal\package_manager\Event\PostApplyEvent;
@@ -8,32 +10,29 @@ use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 
 /**
  * Clears stale update data once staged changes have been applied.
+ *
+ * @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.
  */
-class UpdateDataSubscriber implements EventSubscriberInterface {
-
-  /**
-   * The update manager service.
-   *
-   * @var \Drupal\update\UpdateManagerInterface
-   */
-  protected $updateManager;
+final class UpdateDataSubscriber implements EventSubscriberInterface {
 
   /**
-   * Constructs an UpdateRefreshSubscriber object.
+   * Constructs an UpdateDataSubscriber object.
    *
-   * @param \Drupal\update\UpdateManagerInterface $update_manager
+   * @param \Drupal\update\UpdateManagerInterface $updateManager
    *   The update manager service.
    */
-  public function __construct(UpdateManagerInterface $update_manager) {
-    $this->updateManager = $update_manager;
+  public function __construct(private readonly UpdateManagerInterface $updateManager) {
   }
 
   /**
    * Clears stale update data.
    *
-   * This will always run after any staging area is applied to the active
-   * directory, since it's likely that core and/or multiple extensions have been
-   * added, removed, or updated.
+   * This will always run after any stage directory changes are applied to the
+   * active directory, since it's likely that core and/or multiple extensions
+   * have been added, removed, or updated.
    */
   public function clearData(): void {
     $this->updateManager->refreshUpdateData();
@@ -43,7 +42,7 @@ class UpdateDataSubscriber implements EventSubscriberInterface {
   /**
    * {@inheritdoc}
    */
-  public static function getSubscribedEvents() {
+  public static function getSubscribedEvents(): array {
     return [
       PostApplyEvent::class => ['clearData', 1000],
     ];

package_manager/src/Exception/ApplyFailedException.php

+<?php
+
+declare(strict_types = 1);
+
+namespace Drupal\package_manager\Exception;
+
+/**
+ * Exception thrown if a stage encounters an error applying an update.
+ *
+ * If this exception is thrown it indicates that an update of the active
+ * codebase was attempted but failed. If this happens the site code is in an
+ * indeterminate state. Package Manager does not provide a method for recovering
+ * from this state. The site code should be restored from a backup.
+ *
+ * This exception is different from StageFailureMarkerException in that it is
+ * thrown if an error happens *during* the apply operation, rather than before
+ * or after it.
+ *
+ * Should not be thrown by external code.
+ */
+final class ApplyFailedException extends StageException {
+}

package_manager/src/Exception/ComposerNotReadyException.php

+<?php
+
+declare(strict_types = 1);
+
+namespace Drupal\package_manager\Exception;
+
+/**
+ * Exception thrown if we cannot reliably use Composer.
+ *
+ * Should not be thrown by external code.
+ *
+ * @see \Drupal\package_manager\ComposerInspector::validate()
+ */
+final class ComposerNotReadyException extends \RuntimeException {
+
+  /**
+   * Constructs an ComposerNotReadyException object.
+   *
+   * @param string|null $workingDir
+   *   The directory where Composer was run , or NULL if the errors are related
+   *   to the Composer executable itself.
+   * @param array $messages
+   *   An array of messages explaining why Composer cannot be run correctly.
+   * @param int $code
+   *   (optional) The exception code. Defaults to 0.
+   * @param \Throwable|null $previous
+   *   (optional) The previous exception, for exception chaining.
+   */
+  public function __construct(public readonly ?string $workingDir, array $messages, int $code = 0, ?\Throwable $previous = NULL) {
+    parent::__construct(implode("\n", $messages), $code, $previous);
+  }
+
+}

package_manager/src/Exception/StageEventException.php

+<?php
+
+declare(strict_types = 1);
+
+namespace Drupal\package_manager\Exception;
+
+use Drupal\package_manager\Event\PreOperationStageEvent;
+use Drupal\package_manager\Event\StageEvent;
+
+/**
+ * Exception thrown if an error related to an event occurs.
+ *
+ * This exception is thrown when an error strictly associated with an event
+ * occurs. This is also what makes it different from StageException.
+ *
+ * Should not be thrown by external code.
+ */
+class StageEventException extends StageException {
+
+  /**
+   * Constructs a StageEventException object.
+   *
+   * @param \Drupal\package_manager\Event\StageEvent $event
+   *   The stage event during which this exception is thrown.
+   * @param string|null $message
+   *   (optional) The exception message. Defaults to a plain text representation
+   *   of the validation results.
+   * @param mixed ...$arguments
+   *   Additional arguments to pass to the parent constructor.
+   */
+  public function __construct(public readonly StageEvent $event, ?string $message = NULL, ...$arguments) {
+    parent::__construct($event->stage, $message ?: $this->getResultsAsText(), ...$arguments);
+  }
+
+  /**
+   * Formats the validation results, if any, as plain text.
+   *
+   * @return string
+   *   The results, formatted as plain text.
+   */
+  protected function getResultsAsText(): string {
+    $text = '';
+    if ($this->event instanceof PreOperationStageEvent) {
+      foreach ($this->event->getResults() as $result) {
+        $messages = $result->messages;
+        $summary = $result->summary;
+        if ($summary) {
+          array_unshift($messages, $summary);
+        }
+        $text .= implode("\n", $messages) . "\n";
+      }
+    }
+    return $text;
+  }
+
+}

package_manager/src/Exception/StageException.php

 <?php
 
+declare(strict_types = 1);
+
 namespace Drupal\package_manager\Exception;
 
+use Drupal\package_manager\StageBase;
+
 /**
- * Base class for all exceptions related to staging operations.
+ * Base class for all exceptions related to stage operations.
  *
  * Should not be thrown by external code.
  */
 class StageException extends \RuntimeException {
+
+  /**
+   * Constructs a StageException object.
+   *
+   * @param \Drupal\package_manager\StageBase $stage
+   *   The stage.
+   * @param mixed ...$arguments
+   *   Additional arguments to pass to the parent constructor.
+   */
+  public function __construct(public readonly StageBase $stage, ...$arguments) {
+    parent::__construct(...$arguments);
+  }
+
 }

package_manager/src/Exception/StageFailureMarkerException.php

+<?php
+
+declare(strict_types = 1);
+
+namespace Drupal\package_manager\Exception;
+
+/**
+ * Exception thrown if a stage can't be created due to an earlier failed commit.
+ *
+ * If this exception is thrown it indicates that an earlier commit operation had
+ * failed. If this happens the site code is in an indeterminate state. Package
+ * Manager does not provide a method for recovering from this state. The site
+ * code should be restored from a backup.
+ *
+ * We are extending RuntimeException rather than StageException which makes it
+ * clearer that it's unrelated to the stage life cycle.
+ *
+ * This exception is different from ApplyFailedException as it focuses on
+ * the failure marker being detected outside the stage lifecycle.
+ */
+final class StageFailureMarkerException extends \RuntimeException {
+}

package_manager/src/Exception/StageOwnershipException.php

 <?php
 
+declare(strict_types = 1);
+
 namespace Drupal\package_manager\Exception;
 
 /**
@@ -7,5 +9,5 @@ namespace Drupal\package_manager\Exception;
  *
  * Should not be thrown by external code.
  */
-class StageOwnershipException extends StageException {
+final class StageOwnershipException extends StageException {
 }

package_manager/src/Exception/StageValidationException.php

-<?php
-
-namespace Drupal\package_manager\Exception;
-
-/**
- * Exception thrown if a stage has validation errors.
- *
- * Should not be thrown by external code.
- */
-class StageValidationException extends StageException {
-
-  /**
-   * Any relevant validation results.
-   *
-   * @var \Drupal\package_manager\ValidationResult[]
-   */
-  protected $results = [];
-
-  /**
-   * Constructs a StageException object.
-   *
-   * @param \Drupal\package_manager\ValidationResult[] $results
-   *   Any relevant validation results.
-   * @param mixed ...$arguments
-   *   Arguments to pass to the parent constructor.
-   */
-  public function __construct(array $results = [], ...$arguments) {
-    $this->results = $results;
-    parent::__construct(...$arguments);
-  }
-
-  /**
-   * Gets the validation results.
-   *
-   * @return \Drupal\package_manager\ValidationResult[]
-   *   The validation results.
-   */
-  public function getResults(): array {
-    return $this->results;
-  }
-
-}

package_manager/src/ExecutableFinder.php

 <?php
 
+declare(strict_types = 1);
+
 namespace Drupal\package_manager;
 
 use Drupal\Core\Config\ConfigFactoryInterface;
-use PhpTuf\ComposerStager\Infrastructure\Process\ExecutableFinderInterface;
-use PhpTuf\ComposerStager\Infrastructure\Process\ExecutableFinder as StagerExecutableFinder;
-use Symfony\Component\Process\ExecutableFinder as SymfonyExecutableFinder;
+use PhpTuf\ComposerStager\API\Finder\Service\ExecutableFinderInterface;
 
 /**
  * An executable finder which looks for executable paths in configuration.
+ *
+ * @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.
  */
-class ExecutableFinder implements ExecutableFinderInterface {
-
-  /**
-   * The decorated executable finder.
-   *
-   * @var \PhpTuf\ComposerStager\Infrastructure\Process\ExecutableFinder
-   */
-  private $decorated;
-
-  /**
-   * The config factory service.
-   *
-   * @var \Drupal\Core\Config\ConfigFactoryInterface
-   */
-  private $configFactory;
+final class ExecutableFinder implements ExecutableFinderInterface {
 
   /**
    * Constructs an ExecutableFinder object.
    *
-   * @param \Symfony\Component\Process\ExecutableFinder $symfony_executable_finder
-   *   The Symfony executable finder.
-   * @param \Drupal\Core\Config\ConfigFactoryInterface $config_factory
+   * @param \PhpTuf\ComposerStager\API\Finder\Service\ExecutableFinderInterface $decorated
+   *   The decorated executable finder.
+   * @param \Drupal\Core\Config\ConfigFactoryInterface $configFactory
    *   The config factory service.
    */
-  public function __construct(SymfonyExecutableFinder $symfony_executable_finder, ConfigFactoryInterface $config_factory) {
-    $this->decorated = new StagerExecutableFinder($symfony_executable_finder);
-    $this->configFactory = $config_factory;
-  }
+  public function __construct(
+    private readonly ExecutableFinderInterface $decorated,
+    private readonly ConfigFactoryInterface $configFactory
+  ) {}
 
   /**
    * {@inheritdoc}

package_manager/src/FailureMarker.php

+<?php
+
+declare(strict_types = 1);
+
+namespace Drupal\package_manager;
+
+use Drupal\package_manager\Event\CollectPathsToExcludeEvent;
+use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+use Symfony\Component\Yaml\Exception\ParseException;
+use Symfony\Component\Yaml\Yaml;
+use Drupal\Core\StringTranslation\TranslatableMarkup;
+use Drupal\package_manager\Exception\StageFailureMarkerException;
+
+/**
+ * Handles failure marker file operation.
+ *
+ * The failure marker is a file placed in the active directory while staged
+ * code is copied back into it, and then removed afterwards. This allows us to
+ * know if a commit operation failed midway through, which could leave the site
+ * code base in an indeterminate state -- which, in the worst case scenario,
+ * might render Drupal being unable to boot.
+ *
+ * @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 FailureMarker implements EventSubscriberInterface {
+
+  /**
+   * Constructs a FailureMarker object.
+   *
+   * @param \Drupal\package_manager\PathLocator $pathLocator
+   *   The path locator service.
+   */
+  public function __construct(private readonly PathLocator $pathLocator) {
+  }
+
+  /**
+   * Gets the marker file path.
+   *
+   * @return string
+   *   The absolute path of the marker file.
+   */
+  public function getPath(): string {
+    return $this->pathLocator->getProjectRoot() . '/PACKAGE_MANAGER_FAILURE.yml';
+  }
+
+  /**
+   * Deletes the marker file.
+   */
+  public function clear(): void {
+    unlink($this->getPath());
+  }
+
+  /**
+   * Writes data to marker file.
+   *
+   * @param \Drupal\package_manager\StageBase $stage
+   *   The stage.
+   * @param \Drupal\Core\StringTranslation\TranslatableMarkup $message
+   *   Failure message to be added.
+   * @param \Throwable $throwable
+   *   (optional) The throwable that caused the failure.
+   */
+  public function write(StageBase $stage, TranslatableMarkup $message, \Throwable $throwable = NULL): void {
+    $data = [
+      'stage_class' => get_class($stage),
+      'stage_type' => $stage->getType(),
+      'stage_file' => (new \ReflectionObject($stage))->getFileName(),
+      'message' => (string) $message,
+      'throwable_class' => $throwable ? get_class($throwable) : FALSE,
+      'throwable_message' => $throwable?->getMessage() ?? 'Not available',
+      'throwable_backtrace' => $throwable?->getTraceAsString() ?? 'Not available.',
+    ];
+    file_put_contents($this->getPath(), Yaml::dump($data));
+  }
+
+  /**
+   * Gets the data from the file if it exists.
+   *
+   * @return array|null
+   *   The data from the file if it exists.
+   *
+   * @throws \Drupal\package_manager\Exception\StageFailureMarkerException
+   *   Thrown if failure marker exists but cannot be decoded.
+   */
+  private function getData(): ?array {
+    $path = $this->getPath();
+    if (file_exists($path)) {
+      $data = file_get_contents($path);
+      try {
+        return Yaml::parse($data);
+
+      }
+      catch (ParseException $exception) {
+        throw new StageFailureMarkerException('Failure marker file exists but cannot be decoded.', $exception->getCode(), $exception);
+      }
+    }
+    return NULL;
+  }
+
+  /**
+   * Gets the message from the file if it exists.
+   *
+   * @param bool $include_backtrace
+   *   Whether to include the backtrace in the message. Defaults to TRUE. May be
+   *   set to FALSE in a context where it does not make sense to include, such
+   *   as emails.
+   *
+   * @return string|null
+   *   The message from the file if it exists, otherwise NULL.
+   *
+   * @throws \Drupal\package_manager\Exception\StageFailureMarkerException
+   *   Thrown if failure marker exists but cannot be decoded.
+   */
+  public function getMessage(bool $include_backtrace = TRUE): ?string {
+    $data = $this->getData();
+    if ($data === NULL) {
+      return NULL;
+    }
+    $message = $data['message'];
+    if ($data['throwable_class']) {
+      $message .= sprintf(
+        ' Caused by %s, with this message: %s',
+        $data['throwable_class'],
+        $data['throwable_message'],
+      );
+      if ($include_backtrace) {
+        $message .= "\nBacktrace:\n" . $data['throwable_backtrace'];
+      }
+    }
+    return $message;
+  }
+
+  /**
+   * Asserts the failure file doesn't exist.
+   *
+   * @throws \Drupal\package_manager\Exception\StageFailureMarkerException
+   *   Thrown if the marker file exists.
+   */
+  public function assertNotExists(): void {
+    if ($message = $this->getMessage()) {
+      throw new StageFailureMarkerException($message);
+    }
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public static function getSubscribedEvents(): array {
+    return [
+      CollectPathsToExcludeEvent::class => 'excludeMarkerFile',
+    ];
+  }
+
+  /**
+   * Excludes the failure marker file from stage operations.
+   *
+   * @param \Drupal\package_manager\Event\CollectPathsToExcludeEvent $event
+   *   The event being handled.
+   */
+  public function excludeMarkerFile(CollectPathsToExcludeEvent $event): void {
+    $event->addPathsRelativeToProjectRoot([
+      $this->getPath(),
+    ]);
+  }
+
+}

package_manager/src/FileSyncerFactory.php

 <?php
 
+declare(strict_types = 1);
+
 namespace Drupal\package_manager;
 
 use Drupal\Core\Config\ConfigFactoryInterface;
-use PhpTuf\ComposerStager\Domain\FileSyncer\FileSyncerFactoryInterface;
-use PhpTuf\ComposerStager\Domain\FileSyncer\FileSyncerInterface;
-use PhpTuf\ComposerStager\Infrastructure\FileSyncer\FileSyncerFactory as StagerFileSyncerFactory;
-use Symfony\Component\Process\ExecutableFinder;
+use PhpTuf\ComposerStager\API\FileSyncer\Factory\FileSyncerFactoryInterface;
+use PhpTuf\ComposerStager\API\FileSyncer\Service\FileSyncerInterface;
+use PhpTuf\ComposerStager\API\FileSyncer\Service\PhpFileSyncerInterface;
+use PhpTuf\ComposerStager\API\FileSyncer\Service\RsyncFileSyncerInterface;
 
 /**
  * A file syncer factory which creates a file syncer according to configuration.
+ *
+ * @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.
  */
-class FileSyncerFactory implements FileSyncerFactoryInterface {
-
-  /**
-   * The decorated file syncer factory.
-   *
-   * @var \PhpTuf\ComposerStager\Domain\FileSyncer\FileSyncerFactoryInterface
-   */
-  protected $decorated;
-
-  /**
-   * The PHP file syncer service.
-   *
-   * @var \PhpTuf\ComposerStager\Domain\FileSyncer\FileSyncerInterface
-   */
-  protected $phpFileSyncer;
+final class FileSyncerFactory implements FileSyncerFactoryInterface {
 
   /**
-   * The rsync file syncer service.
+   * Constructs a FileSyncerFactory object.
    *
-   * @var \PhpTuf\ComposerStager\Domain\FileSyncer\FileSyncerInterface
-   */
-  protected $rsyncFileSyncer;
-
-  /**
-   * The config factory service.
-   *
-   * @var \Drupal\Core\Config\ConfigFactoryInterface
-   */
-  protected $configFactory;
-
-  /**
-   * Constructs a FileCopierFactory object.
-   *
-   * @param \Symfony\Component\Process\ExecutableFinder $executable_finder
-   *   The Symfony executable finder.
-   * @param \PhpTuf\ComposerStager\Domain\FileSyncer\FileSyncerInterface $php_file_syncer
+   * @param \PhpTuf\ComposerStager\API\FileSyncer\Factory\FileSyncerFactoryInterface $decorated
+   *   The decorated file syncer factory.
+   * @param \PhpTuf\ComposerStager\API\FileSyncer\Service\PhpFileSyncerInterface $phpFileSyncer
    *   The PHP file syncer service.
-   * @param \PhpTuf\ComposerStager\Domain\FileSyncer\FileSyncerInterface $rsync_file_syncer
+   * @param \PhpTuf\ComposerStager\API\FileSyncer\Service\RsyncFileSyncerInterface $rsyncFileSyncer
    *   The rsync file syncer service.
-   * @param \Drupal\Core\Config\ConfigFactoryInterface $config_factory
+   * @param \Drupal\Core\Config\ConfigFactoryInterface $configFactory
    *   The config factory service.
    */
-  public function __construct(ExecutableFinder $executable_finder, FileSyncerInterface $php_file_syncer, FileSyncerInterface $rsync_file_syncer, ConfigFactoryInterface $config_factory) {
-    $this->decorated = new StagerFileSyncerFactory($executable_finder, $php_file_syncer, $rsync_file_syncer);
-    $this->phpFileSyncer = $php_file_syncer;
-    $this->rsyncFileSyncer = $rsync_file_syncer;
-    $this->configFactory = $config_factory;
-  }
+  public function __construct(
+    private readonly FileSyncerFactoryInterface $decorated,
+    private readonly PhpFileSyncerInterface $phpFileSyncer,
+    private readonly RsyncFileSyncerInterface $rsyncFileSyncer,
+    private readonly ConfigFactoryInterface $configFactory,
+  ) {}
 
   /**
    * {@inheritdoc}