feature #3950 [Components][EventDispatcher] describe the usage of the…

… RegisterListenersPass (xabbuh)

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

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::