diff --git a/doctrine/event_listeners_subscribers.rst b/doctrine/event_listeners_subscribers.rst index 911b3cb6b4a..510b722f7ec 100644 --- a/doctrine/event_listeners_subscribers.rst +++ b/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 + + + + + + + + + + + + .. 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 ` + .. _`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