feature #3950 [Components][EventDispatcher] describe the usage of the RegisterListenersPass (xabbuh)

weaverryan · weaverryan · commit fdb8a324b07c · 2014-08-16T12:22:38.000-04:00
This PR was merged into the 2.3 branch. Discussion ---------- [Components][EventDispatcher] describe the usage of the RegisterListenersPass | Q | A | ------------- | --- | Doc fix? | no | New docs? | yes | Applies to | all | Fixed tickets | #3879 Commits ------- 36407e0 describe the usage of the RegisterListenersPass
diff --git a/components/event_dispatcher/introduction.rst b/components/event_dispatcher/introduction.rst
@@ -205,6 +205,47 @@ instance of ``Symfony\Component\HttpKernel\Event\FilterResponseEvent``::
         // ...
     }
 
+.. sidebar:: Registering Event Listeners in the Service Container
+
+    When you are using the
+    :doc:`DependencyInjection component </components/dependency_injection/introduction>`,
+    you can use the
+    :class:`Symfony\\Component\\HttpKernel\\DependencyInjection\\RegisterListenersPass`
+    from the HttpKernel component to tag services as event listeners::
+
+        use Symfony\Component\DependencyInjection\ContainerBuilder;
+        use Symfony\Component\DependencyInjection\Definition;
+        use Symfony\Component\DependencyInjection\ParameterBag\ParameterBag;
+        use Symfony\Component\HttpKernel\DependencyInjection\RegisterListenersPass;
+
+        $containerBuilder = new ContainerBuilder(new ParameterBag());
+        $containerBuilder->addCompilerPass(new RegisterListenersPass());
+
+        // register the event dispatcher service
+        $containerBuilder->register(
+            'event_dispatcher',
+            'Symfony\Component\EventDispatcher\EventDispatcher'
+        );
+
+        // register your event listener service
+        $listener = new Definition('AcmeListener');
+        $listener->addTag('kernel.event_listener', array(
+            'event' => 'foo.action',
+            'method' => 'onFooAction',
+        ));
+        $containerBuilder->setDefinition('listener_service_id', $listener);
+
+        // register an event subscriber
+        $subscriber = new Definition('AcmeSubscriber');
+        $subscriber->addTag('kernel.event_subscriber');
+        $containerBuilder->setDefinition('subscriber_service_id', $subscriber);
+
+    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``.
+
 .. _event_dispatcher-closures-as-listeners:
 
 .. index::
