CollectIgnoredPathsEvent introduced as a single way to ignore a set of paths

Composer Stager supports the ability to exclude specific paths from staging operations in two main circumstances:

• When the staging area is being created, excluded paths will not be copied from the active directory.
• When the staged changes are being synced back to the active directory, excluded paths will not be copied from the staging area back to the active directory. This also prevents paths which exist in the staging area, but not the active directory, from being deleted in the active directory (this is because Composer Stager tries to keep the active and stage directories in sync with each other; it doesn't just blindly copy stuff from the staging directory and call it a day).

Prior to #3304365: Do not check excluded folders for symlinks, Automatic Updates allowed subscribers to PreCreateEvent and PreApplyEvent to specify paths to exclude. However, the behavior was confusing, since Composer Stager will deal with excluded paths differently depending on whether it's about to create the stage, or apply it (as described above). Additionally, there was no way to exclude paths during a status check, which may be necessary in some situations (for example, when scanning for symlinks, it may be necessary to exclude some directories from the scan).

We now have introduced a new event, \Drupal\package_manager\Event\CollectIgnoredPathsEvent, to make this simpler and more consistent. It is dispatched before status checks, PreCreateEvent, and PreApplyEvent. Event subscribers should use this event to exclude paths that should always be ignored by Composer Stager. Example usage:

function excludeSomePaths(CollectIgnoredPathsEvent $event) {
  $event->add([
    'web/modules/example/private-file.txt',
    'private_files',
  ]);
}

Using this event means that subscribers don't need to worry about subscribing to StatusCheckEvent, PreCreateEvent, or PreApplyEvent separately in order to exclude paths from them.

This change has also deprecated \Drupal\package_manager\Event\ExcludedPathsTrait::excludePath(), which is available on all three events. You should use CollectIgnoredPathsEvent instead.

Additionally, if your code needs to perform a status check, it is strongly recommended to use \Drupal\package_manager\StatusCheckTrait to do it, since it will also transparently dispatch and handle CollectIgnoredPathsEvent.