feature #36243 [Security] Refactor logout listener to dispatch an event instead (wouterj)

This PR was squashed before being merged into the 5.1-dev branch.

Discussion
----------

[Security] Refactor logout listener to dispatch an event instead

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | yes (sort of...)
| New feature?  | yes
| Deprecations? | yes
| Tickets       | Fix #25212, Fix #22473
| License       | MIT
| Doc PR        | tbd

The current `LogoutListener` has some extension points, but they are not really DX-friendly (ref #25212). It requires hacking a `addMethodCall('addHandler')` in the container builder to register a custom logout handler.
Also, it is impossible to overwrite the default logout functionality from a bundle (ref #22473).

This PR introduces a `LogoutEvent` that replaces both the `LogoutSuccessHandlerInterface` and `LogoutHandlerInterface`. This provides a DX-friendly extension point and also cleans up the authentication factories (no more `addMethodCall()`'s).

In order to allow different logout handlers for different firewalls, I created a specific event dispatcher for each firewall (as also shortly discussed in #33558). The `dispatcher` tag attribute allows you to specify which dispatcher it should be registered to (defaulting to the global dispatcher). The `EventBubblingLogoutListener` also dispatches logout events on the global dispatcher, to be used for listeners that should run on all firewalls.

_@weaverryan and I discussed this feature while working on #33558, but figured it was unrelated and could be done while preservering BC. So that's why a separate PR is created._

Commits
-------

a9f096eb1f [Security] Refactor logout listener to dispatch an event instead

Author: fabpot

CHANGELOG.md

@@ -5,6 +5,7 @@ CHANGELOG
 -----
 
  * The `LegacyEventDispatcherProxy` class has been deprecated.
+ * Added an optional `dispatcher` attribute to the listener and subscriber tags in `RegisterListenerPass`.
 
 5.0.0
 -----

DependencyInjection/RegisterListenersPass.php

@@ -61,7 +61,7 @@ public function process(ContainerBuilder $container)
         } else {
             $aliases = [];
         }
-        $definition = $container->findDefinition($this->dispatcherService);
+        $globalDispatcherDefinition = $container->findDefinition($this->dispatcherService);
 
         foreach ($container->findTaggedServiceIds($this->listenerTag, true) as $id => $events) {
             foreach ($events as $event) {
@@ -90,7 +90,12 @@ public function process(ContainerBuilder $container)
                     }
                 }
 
-                $definition->addMethodCall('addListener', [$event['event'], [new ServiceClosureArgument(new Reference($id)), $event['method']], $priority]);
+                $dispatcherDefinition = $globalDispatcherDefinition;
+                if (isset($event['dispatcher'])) {
+                    $dispatcherDefinition = $container->getDefinition($event['dispatcher']);
+                }
+
+                $dispatcherDefinition->addMethodCall('addListener', [$event['event'], [new ServiceClosureArgument(new Reference($id)), $event['method']], $priority]);
 
                 if (isset($this->hotPathEvents[$event['event']])) {
                     $container->getDefinition($id)->addTag($this->hotPathTagName);
@@ -100,7 +105,7 @@ public function process(ContainerBuilder $container)
 
         $extractingDispatcher = new ExtractingEventDispatcher();
 
-        foreach ($container->findTaggedServiceIds($this->subscriberTag, true) as $id => $attributes) {
+        foreach ($container->findTaggedServiceIds($this->subscriberTag, true) as $id => $tags) {
             $def = $container->getDefinition($id);
 
             // We must assume that the class value has been correctly filled, even if the service is created by a factory
@@ -114,12 +119,27 @@ public function process(ContainerBuilder $container)
             }
             $class = $r->name;
 
+            $dispatcherDefinitions = [];
+            foreach ($tags as $attributes) {
+                if (!isset($attributes['dispatcher']) || isset($dispatcherDefinitions[$attributes['dispatcher']])) {
+                    continue;
+                }
+
+                $dispatcherDefinitions[] = $container->getDefinition($attributes['dispatcher']);
+            }
+
+            if ([] === $dispatcherDefinitions) {
+                $dispatcherDefinitions = [$globalDispatcherDefinition];
+            }
+
             ExtractingEventDispatcher::$aliases = $aliases;
             ExtractingEventDispatcher::$subscriber = $class;
             $extractingDispatcher->addSubscriber($extractingDispatcher);
             foreach ($extractingDispatcher->listeners as $args) {
                 $args[1] = [new ServiceClosureArgument(new Reference($id)), $args[1]];
-                $definition->addMethodCall('addListener', $args);
+                foreach ($dispatcherDefinitions as $dispatcherDefinition) {
+                    $dispatcherDefinition->addMethodCall('addListener', $args);
+                }
 
                 if (isset($this->hotPathEvents[$args[0]])) {
                     $container->getDefinition($id)->addTag($this->hotPathTagName);