Doctrine Events

Doctrine Events

Doctrine, the set of PHP libraries used by Symfony to work with databases, provides a lightweight event system to update entities during the application execution. These events, called lifecycle events, allow to perform tasks such as “update the createdAt property automatically right before persisting entities of this type”.

Doctrine triggers events before/after performing the most common entity operations (e.g. prePersist/postPersist, preUpdate/postUpdate) and also on other common tasks (e.g. loadClassMetadata, onClear).

There are different ways to listen to these Doctrine events:

  • Lifecycle callbacks, they are defined as public methods on the entity classes and they are called when the events are triggered;
  • Lifecycle listeners and subscribers, they are classes with callback methods for one or more events and they are called for all entities;
  • Entity listeners, they are similar to lifecycle listeners, but they are called only for the entities of a certain class.

These are the drawbacks and advantages of each one:

  • Callbacks have better performance because they only apply to a single entity class, but you can’t reuse the logic for different entities and they don’t have access to Symfony services;
  • Lifecycle listeners and subscribers can reuse logic among different entities and can access Symfony services but their performance is worse because they are called for all entities;
  • Entity listeners have the same advantages of lifecycle listeners and they have better performance because they only apply to a single entity class.

This article only explains the basics about Doctrine events when using them inside a Symfony application. Read the official docs about Doctrine events to learn everything about them.

See also

This article covers listeners and subscribers for Doctrine ORM. If you are using ODM for MongoDB, read the DoctrineMongoDBBundle documentation.

Doctrine Lifecycle Callbacks

Lifecycle callbacks are defined as public methods inside the entity you want to modify. For example, suppose you want to set a createdAt date column to the current date, but only when the entity is first persisted (i.e. inserted). To do so, define a callback for the prePersist Doctrine event:

  • Annotations

    1. // src/Entity/Product.php
    2. namespace App\Entity;
    4. use Doctrine\ORM\Mapping as ORM;
    6. // When using annotations, don't forget to add @ORM\HasLifecycleCallbacks()
    7. // to the class of the entity where you define the callback
    9. /**
    10.  * @ORM\Entity()
    11.  * @ORM\HasLifecycleCallbacks()
    12.  */
    13. class Product
    14. {
    15.     // ...
    17.     /**
    18.      * @ORM\PrePersist
    19.      */
    20.     public function setCreatedAtValue(): void
    21.     {
    22.         $this->createdAt = new \DateTimeImmutable();
    23.     }
    24. }

  • YAML

    1. # config/doctrine/Product.orm.yml
    2. App\Entity\Product:
    3.     type: entity
    4.     # ...
    5.     lifecycleCallbacks:
    6.         prePersist: ['setCreatedAtValue']

  • XML

    1. <!-- config/doctrine/Product.orm.xml -->
    2. <?xml version="1.0" encoding="UTF-8" ?>
    3. <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
    4.     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    5.     xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
    6.         https://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
    8.     <entity name="App\Entity\Product">
    9.         <!-- ... -->
    10.         <lifecycle-callbacks>
    11.             <lifecycle-callback type="prePersist" method="setCreatedAtValue"/>
    12.         </lifecycle-callbacks>
    13.     </entity>
    14. </doctrine-mapping>

Note

Some lifecycle callbacks receive an argument that provides access to useful information such as the current entity manager (e.g. the preUpdate callback receives a PreUpdateEventArgs $event argument).

Doctrine Lifecycle Listeners

Lifecycle listeners are defined as PHP classes that listen to a single Doctrine event on all the application entities. For example, suppose that you want to update some search index whenever a new entity is persisted in the database. To do so, define a listener for the postPersist Doctrine event:

  1. // src/EventListener/SearchIndexer.php
  2. namespace App\EventListener;
  4. use App\Entity\Product;
  5. use Doctrine\Persistence\Event\LifecycleEventArgs;
  7. class SearchIndexer
  8. {
  9.     // the listener methods receive an argument which gives you access to
  10.     // both the entity object of the event and the entity manager itself
  11.     public function postPersist(LifecycleEventArgs $args): void
  12.     {
  13.         $entity = $args->getObject();
  15.         // if this listener only applies to certain entity types,
  16.         // add some code to check the entity type as early as possible
  17.         if (!$entity instanceof Product) {
  18.             return;
  19.         }
  21.         $entityManager = $args->getObjectManager();
  22.         // ... do something with the Product entity
  23.     }
  24. }

The next step is to enable the Doctrine listener in the Symfony application by creating a new service for it and tagging it with the doctrine.event_listener tag:

  • YAML

    1. # config/services.yaml
    2. services:
    3.     # ...
    5.     App\EventListener\SearchIndexer:
    6.         tags:
    7.             -
    8.                 name: 'doctrine.event_listener'
    9.                 # this is the only required option for the lifecycle listener tag
    10.                 event: 'postPersist'
    12.                 # listeners can define their priority in case multiple listeners are associated
    13.                 # to the same event (default priority = 0; higher numbers = listener is run earlier)
    14.                 priority: 500
    16.                 # you can also restrict listeners to a specific Doctrine connection
    17.                 connection: 'default'

  • XML

    1. <!-- config/services.xml -->
    2. <?xml version="1.0" encoding="UTF-8" ?>
    3. <container xmlns="http://symfony.com/schema/dic/services"
    4.     xmlns:doctrine="http://symfony.com/schema/dic/doctrine">
    5.     <services>
    6.         <!-- ... -->
    8.         <!--
    9.             * 'event' is the only required option that defines the lifecycle listener
    10.             * 'priority': used when multiple listeners are associated to the same event
    11.             *             (default priority = 0; higher numbers = listener is run earlier)
    12.             * 'connection': restricts the listener to a specific Doctrine connection
    13.         -->
    14.         <service id="App\EventListener\SearchIndexer">
    15.             <tag name="doctrine.event_listener"
    16.                 event="postPersist"
    17.                 priority="500"
    18.                 connection="default"/>
    19.         </service>
    20.     </services>
    21. </container>

  • PHP

    1. // config/services.php
    2. use App\EventListener\SearchIndexer;
    4. // listeners are applied by default to all Doctrine connections
    5. $container->autowire(SearchIndexer::class)
    6.     ->addTag('doctrine.event_listener', [
    7.         // this is the only required option for the lifecycle listener tag
    8.         'event' => 'postPersist',
    10.         // listeners can define their priority in case multiple listeners are associated
    11.         // to the same event (default priority = 0; higher numbers = listener is run earlier)
    12.         'priority' => 500,
    14.         # you can also restrict listeners to a specific Doctrine connection
    15.         'connection' => 'default',
    16.     ])
    17. ;

Tip

Symfony loads (and instantiates) Doctrine listeners only when the related Doctrine event is actually fired; whereas Doctrine subscribers are always loaded (and instantiated) by Symfony, making them less performant.

Doctrine Entity Listeners

Entity listeners are defined as PHP classes that listen to a single Doctrine event on a single entity class. For example, suppose that you want to send some notifications whenever a User entity is modified in the database. To do so, define a listener for the postUpdate Doctrine event:

  1. // src/EventListener/UserChangedNotifier.php
  2. namespace App\EventListener;
  4. use App\Entity\User;
  5. use Doctrine\Persistence\Event\LifecycleEventArgs;
  7. class UserChangedNotifier
  8. {
  9.     // the entity listener methods receive two arguments:
  10.     // the entity instance and the lifecycle event
  11.     public function postUpdate(User $user, LifecycleEventArgs $event): void
  12.     {
  13.         // ... do something to notify the changes
  14.     }
  15. }

The next step is to enable the Doctrine listener in the Symfony application by creating a new service for it and tagging it with the doctrine.orm.entity_listener tag:

  • YAML

    1. # config/services.yaml
    2. services:
    3.     # ...
    5.     App\EventListener\UserChangedNotifier:
    6.         tags:
    7.             -
    8.                 # these are the options required to define the entity listener
    9.                 name: 'doctrine.orm.entity_listener'
    10.                 event: 'postUpdate'
    11.                 entity: 'App\Entity\User'
    13.                 # these are other options that you may define if needed
    15.                 # set the 'lazy' option to TRUE to only instantiate listeners when they are used
    16.                 # lazy: true
    18.                 # set the 'entity_manager' option if the listener is not associated to the default manager
    19.                 # entity_manager: 'custom'
    21.                 # by default, Symfony looks for a method called after the event (e.g. postUpdate())
    22.                 # if it doesn't exist, it tries to execute the '__invoke()' method, but you can
    23.                 # configure a custom method name with the 'method' option
    24.                 # method: 'checkUserChanges'

  • XML

    1. <!-- config/services.xml -->
    2. <?xml version="1.0" encoding="UTF-8" ?>
    3. <container xmlns="http://symfony.com/schema/dic/services"
    4.     xmlns:doctrine="http://symfony.com/schema/dic/doctrine">
    5.     <services>
    6.         <!-- ... -->
    8.         <service id="App\EventListener\UserChangedNotifier">
    9.             <!--
    10.                 * These are the options required to define the entity listener:
    11.                 *   * name
    12.                 *   * event
    13.                 *   * entity
    14.                 *
    15.                 * These are other options that you may define if needed:
    16.                 *   * lazy: if TRUE, listeners are only instantiated when they are used
    17.                 *   * entity_manager: define it if the listener is not associated to the default manager
    18.                 *   * method: by default, Symfony looks for a method called after the event (e.g. postUpdate())
    19.                 *           if it doesn't exist, it tries to execute the '__invoke()' method, but
    20.                 *           you can configure a custom method name with the 'method' option
    21.             -->
    22.             <tag name="doctrine.orm.entity_listener"
    23.                 event="postUpdate"
    24.                 entity="App\Entity\User"
    25.                 lazy="true"
    26.                 entity_manager="custom"
    27.                 method="checkUserChanges"/>
    28.         </service>
    29.     </services>
    30. </container>

  • PHP

    1. // config/services.php
    2. use App\Entity\User;
    3. use App\EventListener\UserChangedNotifier;
    5. $container->autowire(UserChangedNotifier::class)
    6.     ->addTag('doctrine.orm.entity_listener', [
    7.         // These are the options required to define the entity listener:
    8.         'event' => 'postUpdate',
    9.         'entity' => User::class,
    11.         // These are other options that you may define if needed:
    13.         // set the 'lazy' option to TRUE to only instantiate listeners when they are used
    14.         // 'lazy' => true,
    16.         // set the 'entity_manager' option if the listener is not associated to the default manager
    17.         // 'entity_manager' => 'custom',
    19.         // by default, Symfony looks for a method called after the event (e.g. postUpdate())
    20.         // if it doesn't exist, it tries to execute the '__invoke()' method, but you can
    21.         // configure a custom method name with the 'method' option
    22.         // 'method' => 'checkUserChanges',
    23.     ])
    24. ;

New in version 4.4: Support for invokable listeners (using the __invoke() method) was introduced in Symfony 4.4.

Doctrine Lifecycle Subscribers

Lifecycle subscribers are defined as PHP classes that implement the Doctrine\Common\EventSubscriber interface and which listen to one or more Doctrine events on all the application entities. For example, suppose that you want to log all the database activity. To do so, define a subscriber for the postPersist, postRemove and postUpdate Doctrine events:

  1. // src/EventListener/DatabaseActivitySubscriber.php
  2. namespace App\EventListener;
  4. use App\Entity\Product;
  5. use Doctrine\Common\EventSubscriber;
  6. use Doctrine\ORM\Events;
  7. use Doctrine\Persistence\Event\LifecycleEventArgs;
  9. class DatabaseActivitySubscriber implements EventSubscriber
  10. {
  11.     // this method can only return the event names; you cannot define a
  12.     // custom method name to execute when each event triggers
  13.     public function getSubscribedEvents(): array
  14.     {
  15.         return [
  16.             Events::postPersist,
  17.             Events::postRemove,
  18.             Events::postUpdate,
  19.         ];
  20.     }
  22.     // callback methods must be called exactly like the events they listen to;
  23.     // they receive an argument of type LifecycleEventArgs, which gives you access
  24.     // to both the entity object of the event and the entity manager itself
  25.     public function postPersist(LifecycleEventArgs $args): void
  26.     {
  27.         $this->logActivity('persist', $args);
  28.     }
  30.     public function postRemove(LifecycleEventArgs $args): void
  31.     {
  32.         $this->logActivity('remove', $args);
  33.     }
  35.     public function postUpdate(LifecycleEventArgs $args): void
  36.     {
  37.         $this->logActivity('update', $args);
  38.     }
  40.     private function logActivity(string $action, LifecycleEventArgs $args): void
  41.     {
  42.         $entity = $args->getObject();
  44.         // if this subscriber only applies to certain entity types,
  45.         // add some code to check the entity type as early as possible
  46.         if (!$entity instanceof Product) {
  47.             return;
  48.         }
  50.         // ... get the entity information and log it somehow
  51.     }
  52. }

The next step is to enable the Doctrine subscriber in the Symfony application by creating a new service for it and tagging it with the doctrine.event_subscriber tag:

  • YAML

    1. # config/services.yaml
    2. services:
    3.     # ...
    5.     App\EventListener\DatabaseActivitySubscriber:
    6.         tags:
    7.             - { name: 'doctrine.event_subscriber' }

  • XML

    1. <!-- config/services.xml -->
    2. <?xml version="1.0" encoding="UTF-8" ?>
    3. <container xmlns="http://symfony.com/schema/dic/services"
    4.     xmlns:doctrine="http://symfony.com/schema/dic/doctrine">
    5.     <services>
    6.         <!-- ... -->
    8.         <service id="App\EventListener\DatabaseActivitySubscriber">
    9.             <tag name="doctrine.event_subscriber"/>
    10.         </service>
    11.     </services>
    12. </container>

  • PHP

    1. // config/services.php
    2. use App\EventListener\DatabaseActivitySubscriber;
    4. $container->autowire(DatabaseActivitySubscriber::class)
    5.     ->addTag('doctrine.event_subscriber')
    6. ;

If you need to associate the subscriber with a specific Doctrine connection, you can do it in the service configuration:

  • YAML

    1. # config/services.yaml
    2. services:
    3.     # ...
    5.     App\EventListener\DatabaseActivitySubscriber:
    6.         tags:
    7.             - { name: 'doctrine.event_subscriber', connection: 'default' }

  • XML

    1. <!-- config/services.xml -->
    2. <?xml version="1.0" encoding="UTF-8" ?>
    3. <container xmlns="http://symfony.com/schema/dic/services"
    4.     xmlns:doctrine="http://symfony.com/schema/dic/doctrine">
    5.     <services>
    6.         <!-- ... -->
    8.         <service id="App\EventListener\DatabaseActivitySubscriber">
    9.             <tag name="doctrine.event_subscriber" connection="default"/>
    10.         </service>
    11.     </services>
    12. </container>

  • PHP

    1. // config/services.php
    2. use App\EventListener\DatabaseActivitySubscriber;
    4. $container->autowire(DatabaseActivitySubscriber::class)
    5.     ->addTag('doctrine.event_subscriber', ['connection' => 'default'])
    6. ;

Tip

Symfony loads (and instantiates) Doctrine subscribers whenever the application executes; whereas Doctrine listeners are only loaded when the related event is actually fired, making them more performant.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.