Configuring the Listener/Subscriber

To register a service to act as an event listener or subscriber you just have to tag it with the appropriate name. Depending on your use-case, you can hook a listener into every DBAL connection and ORM entity manager or just into one specific DBAL connection and all the entity managers that use this connection.

1
2
3
4
5
6
7
8
9
10
11
12

services:
    # ...

    App\EventListener\SearchIndexer:
        tags:
            - { name: doctrine.event_listener, event: postPersist }
    App\EventListener\SearchIndexer2:
        tags:
            - { name: doctrine.event_listener, event: postPersist, connection: default }
    App\EventListener\SearchIndexerSubscriber:
        tags:
            - { name: doctrine.event_subscriber, connection: default }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:doctrine="http://symfony.com/schema/dic/doctrine">
    <services>
        <!-- ... -->

        <service id="App\EventListener\SearchIndexer">
            <tag name="doctrine.event_listener" event="postPersist" />
        </service>
        <service id="App\EventListener\SearchIndexer2">
            <tag name="doctrine.event_listener" event="postPersist" connection="default" />
        </service>
        <service id="App\EventListener\SearchIndexerSubscriber">
            <tag name="doctrine.event_subscriber" connection="default" />
        </service>
    </services>
</container>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

use App\EventListener\SearchIndexer;
use App\EventListener\SearchIndexer2;
use App\EventListener\SearchIndexerSubscriber;

$container->autowire(SearchIndexer::class)
    ->addTag('doctrine.event_listener', array('event' => 'postPersist'))
;
$container->autowire(SearchIndexer2::class)
    ->addTag('doctrine.event_listener', array(
        'event' => 'postPersist',
        'connection' => 'default',
    ))
;
$container->autowire(SearchIndexerSubscriber::class)
    ->addTag('doctrine.event_subscriber', array('connection' => 'default'))
;

Creating the Listener Class

In the previous example, a SearchIndexer service was configured as a Doctrine listener on the event postPersist. The class behind that service must have a postPersist() method, which will be called when the event is dispatched:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

// src/EventListener/SearchIndexer.php
namespace App\EventListener;

use Doctrine\ORM\Event\LifecycleEventArgs;
use App\Entity\Product;

class SearchIndexer
{
    public function postPersist(LifecycleEventArgs $args)
    {
        $entity = $args->getEntity();

        // only act on some "Product" entity
        if (!$entity instanceof Product) {
            return;
        }

        $entityManager = $args->getEntityManager();
        // ... do something with the Product
    }
}

In each event, you have access to a LifecycleEventArgs object, which gives you access to both the entity object of the event and the entity manager itself.

One important thing to notice is that a listener will be listening for all entities in your application. So, if you're interested in only handling a specific type of entity (e.g. a Product entity but not a BlogPost entity), you should check for the entity's class type in your method (as shown above).

Creating the Subscriber Class

A Doctrine event subscriber must implement the Doctrine\Common\EventSubscriber interface and have an event method for each event it subscribes to:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

// src/EventListener/SearchIndexerSubscriber.php
namespace App\EventListener;

use Doctrine\Common\EventSubscriber;
// for Doctrine < 2.4: use Doctrine\ORM\Event\LifecycleEventArgs;
use Doctrine\Common\Persistence\Event\LifecycleEventArgs;
use App\Entity\Product;

class SearchIndexerSubscriber implements EventSubscriber
{
    public function getSubscribedEvents()
    {
        return array(
            'postPersist',
            'postUpdate',
        );
    }

    public function postUpdate(LifecycleEventArgs $args)
    {
        $this->index($args);
    }

    public function postPersist(LifecycleEventArgs $args)
    {
        $this->index($args);
    }

    public function index(LifecycleEventArgs $args)
    {
        $entity = $args->getEntity();

        // perhaps you only want to act on some "Product" entity
        if ($entity instanceof Product) {
            $entityManager = $args->getEntityManager();
            // ... do something with the Product
        }
    }
}

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:

1
2
3
4

services:
    App\EventListener\SearchIndexer:
        tags:
            - { name: doctrine.event_listener, event: postPersist, lazy: true }

1
2
3
4
5
6
7
8
9
10

<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:doctrine="http://symfony.com/schema/dic/doctrine">

    <services>
        <service id="App\EventListener\SearchIndexer" autowire="true">
            <tag name="doctrine.event_listener" event="postPersist" lazy="true" />
        </service>
    </services>
</container>

1
2
3
4
5
6

use App\EventListener\SearchIndexer;

$container
    ->autowire(SearchIndexer::class)
    ->addTag('doctrine.event_listener', array('event' => 'postPersist', 'lazy' => 'true'))
;