Deprecated ContainerAwareEventDispatcher

Author: javiereguiluz

components/event_dispatcher.rst

@@ -22,7 +22,7 @@ answer.
 Consider the real-world example where you want to provide a plugin system
 for your project. A plugin should be able to add methods, or do something
 before or after a method is executed, without interfering with other plugins.
-This is not an easy problem to solve with single inheritance, and even if 
+This is not an easy problem to solve with single inheritance, and even if
 multiple inheritance was possible with PHP, it comes with its own drawbacks.
 
 The Symfony EventDispatcher component implements the `Mediator`_ pattern
@@ -187,33 +187,28 @@ event. In many cases, a special event subclass is passed with extra
 information. You can check the documentation or implementation of each event to
 determine which instance is passed.
 
-.. sidebar:: Registering Event Listeners in the Service Container
+.. sidebar:: Registering Event Listeners and Subscribers in the Service Container
 
-    When you are using the
-    :class:`Symfony\\Component\\EventDispatcher\\ContainerAwareEventDispatcher`
-    and the
-    :doc:`DependencyInjection component </components/dependency_injection>`,
-    you can use the
-    :class:`Symfony\\Component\\EventDispatcher\\DependencyInjection\\RegisterListenersPass`
-    to tag services as event listeners::
+    Registering service definitions and tagging them with the
+    ``kernel.event_listener`` and ``kernel.event_subscriber`` tags is not enough
+    to enable the event listeners and event subscribers. You must also register
+    a compiler pass called ``RegisterListenersPass()`` in the container builder::
 
         use Symfony\Component\DependencyInjection\ContainerBuilder;
         use Symfony\Component\DependencyInjection\Definition;
         use Symfony\Component\DependencyInjection\ParameterBag\ParameterBag;
         use Symfony\Component\DependencyInjection\Reference;
-        use Symfony\Component\EventDispatcher\ContainerAwareEventDispatcher;
+        use Symfony\Component\EventDispatcher\EventDispatcher;
         use Symfony\Component\EventDispatcher\DependencyInjection\RegisterListenersPass;
 
         $containerBuilder = new ContainerBuilder(new ParameterBag());
+        // register the compiler pass that handles the 'kernel.event_listener'
+        // and 'kernel.event_subscriber' service tags
         $containerBuilder->addCompilerPass(new RegisterListenersPass());
 
-        // register the event dispatcher service
-        $containerBuilder->setDefinition('event_dispatcher', new Definition(
-            ContainerAwareEventDispatcher::class,
-            array(new Reference('service_container'))
-        ));
+        $containerBuilder->register('event_dispatcher', EventDispatcher::class);
 
-        // register your event listener service
+        // register an event listener
         $listener = new Definition(\AcmeListener::class);
         $listener->addTag('kernel.event_listener', array(
             'event' => 'foo.action',
@@ -441,7 +436,7 @@ EventDispatcher Aware Events and Listeners
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The ``EventDispatcher`` always passes the dispatched event, the event's
-name and a reference to itself to the listeners. This can lead to some advanced 
+name and a reference to itself to the listeners. This can lead to some advanced
 applications of the ``EventDispatcher`` including dispatching other events inside
 listeners, chaining events or even lazy loading listeners into the dispatcher object.
 

components/event_dispatcher/container_aware_dispatcher.rst

@@ -4,6 +4,11 @@
 The Container Aware Event Dispatcher
 ====================================
 
+.. versionadded:: 3.3
+    The ``ContainerAwareEventDispatcher`` class has been deprecated in Symfony 3.3
+    and it will be removed in Symfony 4.0. Use ``EventDispatcher`` with
+    closure-proxy injection instead.
+
 Introduction
 ------------
 

components/event_dispatcher/immutable_dispatcher.rst

@@ -12,9 +12,8 @@ The ``ImmutableEventDispatcher`` takes another event dispatcher with all
 the listeners and subscribers. The immutable dispatcher is just a proxy
 of this original dispatcher.
 
-To use it, first create a normal dispatcher (``EventDispatcher`` or
-``ContainerAwareEventDispatcher``) and register some listeners or
-subscribers::
+To use it, first create a normal ``EventDispatcher`` dispatcher and register
+some listeners or subscribers::
 
     use Symfony\Component\EventDispatcher\EventDispatcher;