[EventDispatcher] Document event name aliases.

derrabus · derrabus · commit c87632c4ec6e · 2019-10-07T16:08:59.000+02:00
diff --git a/components/event_dispatcher.rst b/components/event_dispatcher.rst
@@ -220,11 +220,55 @@ determine which instance is passed.
         $containerBuilder->register('subscriber_service_id', \AcmeSubscriber::class)
             ->addTag('kernel.event_subscriber');
 
+    ``RegisterListenersPass`` is able to resolve aliased class names which for
+    instance allows to refer to an event via the fully qualified class name
+    (FQCN) of the event class. The pass will read the alias mapping from a
+    dedicated container parameter. This parameter can be extended by registering
+    another compiler pass, ``AddEventAliasesPass``::
+
+        use Symfony\Component\DependencyInjection\Compiler\PassConfig;
+        use Symfony\Component\DependencyInjection\ContainerBuilder;
+        use Symfony\Component\DependencyInjection\ParameterBag\ParameterBag;
+        use Symfony\Component\DependencyInjection\Reference;
+        use Symfony\Component\EventDispatcher\DependencyInjection\AddEventAliasesPass;
+        use Symfony\Component\EventDispatcher\DependencyInjection\RegisterListenersPass;
+        use Symfony\Component\EventDispatcher\EventDispatcher;
+
+        $containerBuilder = new ContainerBuilder(new ParameterBag());
+        $containerBuilder->addCompilerPass(new RegisterListenersPass(), PassConfig::TYPE_BEFORE_REMOVING);
+        $containerBuilder->addCompilerPass(new AddEventAliasesPass([
+            \AcmeFooActionEvent::class => 'acme.foo.action',
+        ]));
+
+        $containerBuilder->register('event_dispatcher', EventDispatcher::class);
+
+        // registers an event listener
+        $containerBuilder->register('listener_service_id', \AcmeListener::class)
+            ->addTag('kernel.event_listener', [
+                // will be translated to 'acme.foo.action' by RegisterListenersPass.
+                'event' => \AcmeFooActionEvent::class,
+                'method' => 'onFooAction',
+            ]);
+
+    .. note::
+
+        Note that ``AddEventAliasesPass`` has to be processed before ``RegisterListenersPass``.
+
     By default, the listeners pass assumes that the event dispatcher's service
     id is ``event_dispatcher``, that event listeners are tagged with the
-    ``kernel.event_listener`` tag and that event subscribers are tagged
-    with the ``kernel.event_subscriber`` tag. You can change these default
-    values by passing custom values to the constructor of ``RegisterListenersPass``.
+    ``kernel.event_listener`` tag, that event subscribers are tagged
+    with the ``kernel.event_subscriber`` tag and that the alias mapping is
+    stored as parameter ``event_dispatcher.event_aliases``. You can change these
+    default values by passing custom values to the constructors of
+    ``RegisterListenersPass`` and ``AddEventAliasesPass``.
+
+.. versionadded:: 4.3
+
+    Aliasing event names is possible since Symfony 4.3.
+
+.. versionadded:: 4.4
+
+    The ``AddEventAliasesPass`` class was introduced in Symfony 4.4.
 
 .. _event_dispatcher-closures-as-listeners:
 
diff --git a/event_dispatcher.rst b/event_dispatcher.rst
@@ -246,6 +246,73 @@ there are some minor advantages for each of them:
 * **Listeners are more flexible** because bundles can enable or disable each of
   them conditionally depending on some configuration value.
 
+.. _event-aliases:
+
+Event Aliases
+-------------
+
+When configuring event listeners and subscribers via dependency injection,
+Symfony's core events can also be referred to by the fully qualified class
+name (FQCN) of the corresponding event class::
+
+    // src/EventSubscriber/RequestSubscriber.php
+    namespace App\EventSubscriber;
+
+    use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+    use Symfony\Component\HttpKernel\Event\RequestEvent;
+
+    class RequestSubscriber implements EventSubscriberInterface
+    {
+        public static function getSubscribedEvents(): array
+        {
+            return [
+                RequestEvent::class => 'onKernelRequest',
+            ];
+        }
+
+        public function onKernelRequest(RequestEvent $event)
+        {
+            // ...
+        }
+    }
+
+.. versionadded:: 4.3
+
+    Referring Symfony's core events via the FQCN of the event class is possible
+    since Symfony 4.3.
+
+Internally, the event FQCN are treated as aliases for the original event names.
+Since the mapping already happens when compiling the service container, event
+listeners and subscribers using FQCN instead of event names will appear under
+the original event name when inspecting the event dispatcher.
+
+This alias mapping can be extended for custom events by registering the
+compiler pass ``AddEventAliasesPass``::
+
+    // src/Kernel.php
+    use App\Event\MyCustomEvent;
+    use Symfony\Component\DependencyInjection\ContainerBuilder;
+    use Symfony\Component\EventDispatcher\DependencyInjection\AddEventAliasesPass;
+    use Symfony\Component\HttpKernel\Kernel as BaseKernel;
+
+    class Kernel extends BaseKernel
+    {
+        protected function build(ContainerBuilder $container)
+        {
+            $container->addCompilerPass(new AddEventAliasesPass([
+                MyCustomEvent::class => 'my_custom_event',
+            ]));
+        }
+    }
+
+The compiler pass will always extend the existing list of aliases. Because of
+that, it is safe to register multiple instances of the pass with different
+configurations.
+
+.. versionadded:: 4.4
+
+    The ``AddEventAliasesPass`` class was introduced in Symfony 4.4.
+
 Debugging Event Listeners
 -------------------------
 
