Mention lazy loading for Doctrine event listeners

Author: mpdude

doctrine/event_listeners_subscribers.rst

@@ -214,5 +214,58 @@ interface and have an event method for each event it subscribes to::
 
 For a full reference, see chapter `The Event System`_ in the Doctrine documentation.
 
+Lazy loading for Event Listeners
+--------------------------------
+
+One subtle difference between listeners and subscribers is that Symfony can load 
+entity listeners lazily. This means that your listener class will only be fetched
+from the service container (and thus be instantiated) once the event it is linked
+to actually fires.
+
+Lazy loading might give you a slight performance improvement when your listener 
+runs for events that rarely fire. Also, it can help you when you run into 
+*circular dependency issues* that may occur when your listener service in turn
+depends on the DBAL connection. 
+
+To mark a listener service as lazily loaded, just add the ``lazy`` attribute
+to the tag like so:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        services:
+            my.listener:
+                class: AppBundle\EventListener\SearchIndexer
+                tags:
+                    - { name: doctrine.event_listener, event: postPersist, lazy: true }
+
+    .. code-block:: xml
+
+        <?xml version="1.0" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:doctrine="http://symfony.com/schema/dic/doctrine">
+
+            <services>
+                <service id="my.listener" class="AppBundle\EventListener\SearchIndexer">
+                    <tag name="doctrine.event_listener" event="postPersist" lazy="true" />
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        use AppBundle\EventListener\SearchIndexer;
+
+        $container
+            ->register('my.listener', SearchIndexer::class)
+            ->addTag('doctrine.event_listener', array('event' => 'postPersist', 'lazy' => 'true'))
+        ;
+
+.. note::
+
+    Marking an event listener as ``lazy`` has nothing to do with lazy service
+    definitions which are described :doc:`in their own section </service_container/lazy_services>`
+
 .. _`The Event System`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/events.html
 .. _`the Doctrine Documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/events.html#entity-listeners