Events

Registering Event Handlers

There are two ways to set up an event handler:

• For all events you can create a Lifecycle Event Listener or Subscriber class and register

it by calling $eventManager->addEventListener() or eventManager->addEventSubscriber(), see Listening and subscribing to Lifecycle Events For some events (see table below), you can create a Lifecycle Callback* method in the entity, see Lifecycle Callbacks.

Naming convention

Events being used with the Doctrine ORM EventManager are best named with camelcase and the value of the corresponding constant should be the name of the constant itself, even with spelling. This has several reasons:

• It is easy to read.
• Simplicity.
• Each method within an EventSubscriber is named after the corresponding constant's value. If the constant's name and value differ it contradicts the intention of using the constant and makes your code harder to maintain.

An example for a correct notation can be found in the example TestEvent above.

prePersist

There are two ways for the prePersist event to be triggered:

• One is when you call EntityManager::persist(). The event is also called for all cascaded associations.
• The other is inside the flush() method when changes to associations are computed and this association is marked as cascade: persist. Any new entity found during this operation is also persisted and prePersist called on it. This is called persistence by reachability.

In both cases you get passed a PrePersistEventArgs instance which has access to the entity and the entity manager.

This event is only triggered on initial persist of an entity (i.e. it does not trigger on future updates).

The following restrictions apply to prePersist:

• If you are using a PrePersist Identity Generator such as sequences the ID value will NOT be available within any PrePersist events.
• Doctrine will not recognize changes made to relations in a prePersist event. This includes modifications to collections such as additions, removals or replacement.

preRemove

The preRemove event is called on every entity immediately when it is passed to the EntityManager::remove() method. It is cascaded for all associations that are marked as cascade: remove

It is not called for a DQL DELETE statement.

There are no restrictions to what methods can be called inside the preRemove event, except when the remove method itself was called during a flush operation.

preFlush

preFlush is called inside EntityManager::flush() before anything else. EntityManager::flush() must not be called inside its listeners, since it would fire the preFlush event again, which would result in an infinite loop.

1
<?php
use Doctrine\ORM\Event\PreFlushEventArgs;

class PreFlushExampleListener
{
    public function preFlush(PreFlushEventArgs $args)
    {
        // ...
    }
}
2
3
4
5
6
7
8
9
10

onFlush

onFlush is a very powerful event. It is called inside EntityManager::flush() after the changes to all the managed entities and their associations have been computed. This means, the onFlush event has access to the sets of:

• Entities scheduled for insert
• Entities scheduled for update
• Entities scheduled for removal
• Collections scheduled for update
• Collections scheduled for removal

To make use of the onFlush event you have to be familiar with the internal UnitOfWork API, which grants you access to the previously mentioned sets. See this example:

1
<?php
class FlushExampleListener
{
    public function onFlush(OnFlushEventArgs $eventArgs)
    {
        $em = $eventArgs->getObjectManager();
        $uow = $em->getUnitOfWork();

        foreach ($uow->getScheduledEntityInsertions() as $entity) {

        }

        foreach ($uow->getScheduledEntityUpdates() as $entity) {

        }

        foreach ($uow->getScheduledEntityDeletions() as $entity) {

        }

        foreach ($uow->getScheduledCollectionDeletions() as $col) {

        }

        foreach ($uow->getScheduledCollectionUpdates() as $col) {

        }
    }
}
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

The following restrictions apply to the onFlush event:

• If you create and persist a new entity in onFlush, then calling EntityManager::persist() is not enough. You have to execute an additional call to $unitOfWork->computeChangeSet($classMetadata, $entity).
• Changing primitive fields or associations requires you to explicitly trigger a re-computation of the changeset of the affected entity. This can be done by calling $unitOfWork->recomputeSingleEntityChangeSet($classMetadata, $entity).

postFlush

postFlush is called at the end of EntityManager::flush(). EntityManager::flush() can NOT be called safely inside its listeners. This event is not a lifecycle callback.

1
<?php
use Doctrine\ORM\Event\PostFlushEventArgs;

class PostFlushExampleListener
{
    public function postFlush(PostFlushEventArgs $args)
    {
        // ...
    }
}
2
3
4
5
6
7
8
9
10

preUpdate

PreUpdate is called inside the EntityManager::flush() method, right before an SQL UPDATE statement. This event is not triggered when the computed changeset is empty, nor for a DQL UPDATE statement.

Changes to associations of the updated entity are never allowed in this event, since Doctrine cannot guarantee to correctly handle referential integrity at this point of the flush operation. This event has a powerful feature however, it is executed with a PreUpdateEventArgs instance, which contains a reference to the computed change-set of this entity.

This means you have access to all the fields that have changed for this entity with their old and new value. The following methods are available on the PreUpdateEventArgs:

• getEntity() to get access to the actual entity.
• getEntityChangeSet() to get a copy of the changeset array. Changes to this returned array do not affect updating.
• hasChangedField($fieldName) to check if the given field name of the current entity changed.
• getOldValue($fieldName) and getNewValue($fieldName) to access the values of a field.
• setNewValue($fieldName, $value) to change the value of a field to be updated.

A simple example for this event looks like:

1
<?php
use Doctrine\ORM\Event\PreUpdateEventArgs;

class NeverAliceOnlyBobListener
{
    public function preUpdate(PreUpdateEventArgs $eventArgs)
    {
        if ($eventArgs->getEntity() instanceof User) {
            if ($eventArgs->hasChangedField('name') && $eventArgs->getNewValue('name') == 'Alice') {
                $eventArgs->setNewValue('name', 'Bob');
                // The following will only work if `status` is already present in the computed changeset.
                // Otherwise it will throw an InvalidArgumentException:
                $eventArgs->setNewValue('status', 'active');
            }
        }
    }
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

You could also use this listener to implement validation of all the fields that have changed. This is more efficient than using a lifecycle callback when there are expensive validations to call:

1
<?php
use Doctrine\ORM\Event\PreUpdateEventArgs;

class ValidCreditCardListener
{
    public function preUpdate(PreUpdateEventArgs $eventArgs)
    {
        if ($eventArgs->getEntity() instanceof Account) {
            if ($eventArgs->hasChangedField('creditCard')) {
                $this->validateCreditCard($eventArgs->getNewValue('creditCard'));
            }
        }
    }

    private function validateCreditCard($no)
    {
        // throw an exception to interrupt flush event. Transaction will be rolled back.
    }
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

Restrictions for this event:

• Changes to associations of the passed entities are not recognized by the flush operation anymore.
• Changes to fields of the passed entities are not recognized by the flush operation anymore, use the computed change-set passed to the event to modify primitive field values, e.g. use $eventArgs->setNewValue($field, $value); as in the Alice to Bob example above.
• Any calls to EntityManager::persist() or EntityManager::remove(), even in combination with the UnitOfWork API are strongly discouraged and don't work as expected outside the flush operation.

postUpdate, postRemove, postPersist

These three post* events are called inside EntityManager::flush(). Changes in here are not relevant to the persistence in the database, but you can use these events to alter non-persistable items, like non-mapped fields, logging or even associated classes that are not directly mapped by Doctrine.

• The postUpdate event occurs after the database update operations to entity data, but before the database transaction has been committed. It is not called for a DQL UPDATE statement.
• The postPersist event occurs for an entity after the entity has been made persistent. It will be invoked after all database insert operations for new entities have been performed, but before the database transaction has been committed. Generated primary key values will be available for all entities at the time this event is triggered.
• The postRemove event occurs for an entity after the entity has been deleted. It will be invoked after all database delete operations for entity rows have been executed, but before the database transaction has been committed. This event is not called for a DQL DELETE statement.

postLoad

The postLoad event occurs after the entity has been loaded into the current EntityManager from the database or after refresh() has been applied to it.

onClear

The onClear event occurs when the EntityManager::clear() operation is invoked, after all references to entities have been removed from the unit of work. This event is not a lifecycle callback.

Entity listeners class

An Entity Listener could be any class, by default it should be a class with a no-arg constructor.

• Different from Implementing Event Listeners an Entity Listener is invoked just to the specified entity
• An entity listener method receives two arguments, the entity instance and the lifecycle event.
• The callback method can be defined by naming convention or specifying a method mapping.
• When a listener mapping is not given the parser will use the naming convention to look for a matching method, e.g. it will look for a public preUpdate() method if you are listening to the preUpdate event.
• When a listener mapping is given the parser will not look for any methods using the naming convention.

1
<?php
use Doctrine\ORM\Event\PreUpdateEventArgs;

class UserListener
{
    public function preUpdate(User $user, PreUpdateEventArgs $event)
    {
        // Do something on pre update.
    }
}
2
3
4
5
6
7
8
9
10

To define a specific event listener method (one that does not follow the naming convention) you need to map the listener method using the event type mapping:

1
<?php
use Doctrine\ORM\Event\PostLoadEventArgs;
use Doctrine\ORM\Event\PostPersistEventArgs;
use Doctrine\ORM\Event\PostRemoveEventArgs;
use Doctrine\ORM\Event\PostUpdateEventArgs;
use Doctrine\ORM\Event\PreFlushEventArgs;
use Doctrine\ORM\Event\PrePersistEventArgs;
use Doctrine\ORM\Event\PreRemoveEventArgs;
use Doctrine\ORM\Event\PreUpdateEventArgs;

class UserListener
{
    #[PrePersist]
    public function prePersistHandler(User $user, PrePersistEventArgs $event): void { // ... }

    #[PostPersist]
    public function postPersistHandler(User $user, PostPersistEventArgs $event): void { // ... }

    #[PreUpdate]
    public function preUpdateHandler(User $user, PreUpdateEventArgs $event): void { // ... }

    #[PostUpdate]
    public function postUpdateHandler(User $user, PostUpdateEventArgs $event): void { // ... }

    #[PostRemove]
    public function postRemoveHandler(User $user, PostRemoveEventArgs $event): void { // ... }

    #[PreRemove]
    public function preRemoveHandler(User $user, PreRemoveEventArgs $event): void { // ... }

    #[PreFlush]
    public function preFlushHandler(User $user, PreFlushEventArgs $event): void { // ... }

    #[PostLoad]
    public function postLoadHandler(User $user, PostLoadEventArgs $event): void { // ... }
}
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

1
<doctrine-mapping>
    <entity name="MyProject\Entity\User">
         <entity-listeners>
            <entity-listener class="UserListener">
                <lifecycle-callback type="preFlush"      method="preFlushHandler"/>
                <lifecycle-callback type="postLoad"      method="postLoadHandler"/>

                <lifecycle-callback type="postPersist"   method="postPersistHandler"/>
                <lifecycle-callback type="prePersist"    method="prePersistHandler"/>

                <lifecycle-callback type="postUpdate"    method="postUpdateHandler"/>
                <lifecycle-callback type="preUpdate"     method="preUpdateHandler"/>

                <lifecycle-callback type="postRemove"    method="postRemoveHandler"/>
                <lifecycle-callback type="preRemove"     method="preRemoveHandler"/>
            </entity-listener>
        </entity-listeners>
        <!-- .... -->
    </entity>
</doctrine-mapping>
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

Entity listeners resolver

Doctrine invokes the listener resolver to get the listener instance.

• A resolver allows you register a specific entity listener instance.
• You can also implement your own resolver by extending Doctrine\ORM\Mapping\DefaultEntityListenerResolver or implementing Doctrine\ORM\Mapping\EntityListenerResolver

Specifying an entity listener instance :

1
<?php
use Doctrine\ORM\Event\PreUpdateEventArgs;

// User.php

#[Entity]
#[EntityListeners(["UserListener"])
class User
{
    // ....
}

// UserListener.php
class UserListener
{
    public function __construct(MyService $service)
    {
        $this->service = $service;
    }

    public function preUpdate(User $user, PreUpdateEventArgs $event)
    {
        $this->service->doSomething($user);
    }
}

// register a entity listener.
$listener = $container->get('user_listener');
$em->getConfiguration()->getEntityListenerResolver()->register($listener);
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

Implementing your own resolver:

1
<?php
use Doctrine\ORM\Mapping\DefaultEntityListenerResolver;

class MyEntityListenerResolver extends DefaultEntityListenerResolver
{
    public function __construct($container)
    {
        $this->container = $container;
    }

    public function resolve($className)
    {
        // resolve the service id by the given class name;
        $id = 'user_listener';

        return $this->container->get($id);
    }
}

// Configure the listener resolver only before instantiating the EntityManager
$configurations->setEntityListenerResolver(new MyEntityListenerResolver);
$entityManager = new EntityManager(.., $configurations, ..);
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

postGenerateSchemaTable

This event is fired for each Doctrine\DBAL\Schema\Table instance, after one was created and built up with the current class metadata of an entity. It is possible to access to the current state of Doctrine\DBAL\Schema\Schema, the current table schema instance and class metadata.

1
<?php
use Doctrine\ORM\Tools\ToolEvents;
use Doctrine\ORM\Tools\Event\GenerateSchemaTableEventArgs;

$test = new TestEventListener();
$evm = $em->getEventManager();
$evm->addEventListener(ToolEvents::postGenerateSchemaTable, $test);

class TestEventListener
{
    public function postGenerateSchemaTable(GenerateSchemaTableEventArgs $eventArgs)
    {
        $classMetadata = $eventArgs->getClassMetadata();
        $schema = $eventArgs->getSchema();
        $table = $eventArgs->getClassTable();
    }
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

postGenerateSchema

This event is fired after the schema instance was successfully built and before SQL queries are generated from the schema information of Doctrine\DBAL\Schema\Schema. It allows to access the full object representation of the database schema and the EntityManager.

1
<?php
use Doctrine\ORM\Tools\ToolEvents;
use Doctrine\ORM\Tools\Event\GenerateSchemaEventArgs;

$test = new TestEventListener();
$evm = $em->getEventManager();
$evm->addEventListener(ToolEvents::postGenerateSchema, $test);

class TestEventListener
{
    public function postGenerateSchema(GenerateSchemaEventArgs $eventArgs)
    {
        $schema = $eventArgs->getSchema();
        $em = $eventArgs->getEntityManager();
    }
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16