Events

The Event System

The event system is controlled by the EventManager. It is the central point of Doctrine's event listener system. Listeners are registered on the manager and events are dispatched through the manager.

1
<?php
$evm = new EventManager();
2

Now we can add some event listeners to the $evm. Let's create a TestEvent class to play around with.

1
<?php
class TestEvent
{
    const preFoo = 'preFoo';
    const postFoo = 'postFoo';

    private $_evm;

    public $preFooInvoked = false;
    public $postFooInvoked = false;

    public function __construct($evm)
    {
        $evm->addEventListener(array(self::preFoo, self::postFoo), $this);
    }

    public function preFoo(EventArgs $e)
    {
        $this->preFooInvoked = true;
    }

    public function postFoo(EventArgs $e)
    {
        $this->postFooInvoked = true;
    }
}

// Create a new instance
$test = new TestEvent($evm);
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

Events can be dispatched by using the dispatchEvent() method.

1
<?php
$evm->dispatchEvent(TestEvent::preFoo);
$evm->dispatchEvent(TestEvent::postFoo);
2
3

You can easily remove a listener with the removeEventListener() method.

1
<?php
$evm->removeEventListener(array(self::preFoo, self::postFoo), $this);
2

The Doctrine 2 event system also has a simple concept of event subscribers. We can define a simple TestEventSubscriber class which implements the \Doctrine\Common\EventSubscriber interface and implements a getSubscribedEvents() method which returns an array of events it should be subscribed to.

1
<?php
class TestEventSubscriber implements \Doctrine\Common\EventSubscriber
{
    public $preFooInvoked = false;

    public function preFoo()
    {
        $this->preFooInvoked = true;
    }

    public function getSubscribedEvents()
    {
        return array(TestEvent::preFoo);
    }
}

$eventSubscriber = new TestEventSubscriber();
$evm->addEventSubscriber($eventSubscriber);
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

Now when you dispatch an event, any event subscribers will be notified for that event.

1
<?php
$evm->dispatchEvent(TestEvent::preFoo);
2

Now you can test the $eventSubscriber instance to see if the preFoo() method was invoked.

1
<?php
if ($eventSubscriber->preFooInvoked) {
    echo 'pre foo invoked!';
}
2
3
4

Lifecycle Events

The EntityManager and UnitOfWork trigger a bunch of events during the life-time of their registered entities.

• preRemove - The preRemove event occurs for a given entity before the respective EntityManager remove operation for that entity is executed. It is not called for a DQL DELETE statement.
• postRemove - The postRemove event occurs for an entity after the entity has been deleted. It will be invoked after the database delete operations. It is not called for a DQL DELETE statement.
• prePersist - The prePersist event occurs for a given entity before the respective EntityManager persist operation for that entity is executed. It should be noted that this event is only triggered on initial persist of an entity (i.e. it does not trigger on future updates).
• postPersist - The postPersist event occurs for an entity after the entity has been made persistent. It will be invoked after the database insert operations. Generated primary key values are available in the postPersist event.
• preUpdate - The preUpdate event occurs before the database update operations to entity data. It is not called for a DQL UPDATE statement.
• postUpdate - The postUpdate event occurs after the database update operations to entity data. It is not called for a DQL UPDATE statement.
• postLoad - The postLoad event occurs for an entity after the entity has been loaded into the current EntityManager from the database or after the refresh operation has been applied to it.
• loadClassMetadata - The loadClassMetadata event occurs after the mapping metadata for a class has been loaded from a mapping source (annotations/xml/yaml). This event is not a lifecycle callback.
• onClassMetadataNotFound - Loading class metadata for a particular requested class name failed. Manipulating the given event args instance allows providing fallback metadata even when no actual metadata exists or could be found. This event is not a lifecycle callback.
• preFlush - The preFlush event occurs at the very beginning of a flush operation. This event is not a lifecycle callback.
• onFlush - The onFlush event occurs after the change-sets of all managed entities are computed. This event is not a lifecycle callback.
• postFlush - The postFlush event occurs at the end of a flush operation. This event is not a lifecycle callback.
• 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.

You can access the Event constants from the Events class in the ORM package.

1
<?php
use Doctrine\ORM\Events;
echo Events::preUpdate;
2
3

These can be hooked into by two different types of event listeners:

• Lifecycle Callbacks are methods on the entity classes that are called when the event is triggered. As of v2.4 they receive some kind of EventArgs instance.
• Lifecycle Event Listeners and Subscribers are classes with specific callback methods that receives some kind of EventArgs instance.

The EventArgs instance received by the listener gives access to the entity, EntityManager and other relevant data.

Lifecycle Callbacks

Lifecycle Callbacks are defined on an entity class. They allow you to trigger callbacks whenever an instance of that entity class experiences a relevant lifecycle event. More than one callback can be defined for each lifecycle event. Lifecycle Callbacks are best used for simple operations specific to a particular entity class's lifecycle.

1
<?php

/** @Entity @HasLifecycleCallbacks */
class User
{
    // ...

    /**
     * @Column(type="string", length=255)
     */
    public $value;

    /** @Column(name="created_at", type="string", length=255) */
    private $createdAt;

    /** @PrePersist */
    public function doStuffOnPrePersist()
    {
        $this->createdAt = date('Y-m-d H:i:s');
    }

    /** @PrePersist */
    public function doOtherStuffOnPrePersist()
    {
        $this->value = 'changed from prePersist callback!';
    }

    /** @PostPersist */
    public function doStuffOnPostPersist()
    {
        $this->value = 'changed from postPersist callback!';
    }

    /** @PostLoad */
    public function doStuffOnPostLoad()
    {
        $this->value = 'changed from postLoad callback!';
    }

    /** @PreUpdate */
    public function doStuffOnPreUpdate()
    {
        $this->value = 'changed from preUpdate callback!';
    }
}
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
40
41
42
43
44
45

Note that the methods set as lifecycle callbacks need to be public and, when using these annotations, you have to apply the @HasLifecycleCallbacks marker annotation on the entity class.

If you want to register lifecycle callbacks from YAML or XML you can do it with the following.

1
User:
  type: entity
  fields:
# ...
    name:
      type: string(50)
  lifecycleCallbacks:
    prePersist: [ doStuffOnPrePersist, doOtherStuffOnPrePersist ]
    postPersist: [ doStuffOnPostPersist ]
2
3
4
5
6
7
8
9

In YAML the key of the lifecycleCallbacks entry is the event that you are triggering on and the value is the method (or methods) to call. The allowed event types are the ones listed in the previous Lifecycle Events section.

XML would look something like this:

1
<?xml version="1.0" encoding="UTF-8"?>

<doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                          /Users/robo/dev/php/Doctrine/doctrine-mapping.xsd">

    <entity name="User">

        <lifecycle-callbacks>
            <lifecycle-callback type="prePersist" method="doStuffOnPrePersist"/>
            <lifecycle-callback type="postPersist" method="doStuffOnPostPersist"/>
        </lifecycle-callbacks>

    </entity>

</doctrine-mapping>
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

In XML the type of the lifecycle-callback entry is the event that you are triggering on and the method is the method to call. The allowed event types are the ones listed in the previous Lifecycle Events section.

When using YAML or XML you need to remember to create public methods to match the callback names you defined. E.g. in these examples doStuffOnPrePersist(), doOtherStuffOnPrePersist() and doStuffOnPostPersist() methods need to be defined on your User model.

1
<?php
// ...

class User
{
    // ...

    public function doStuffOnPrePersist()
    {
        // ...
    }

    public function doOtherStuffOnPrePersist()
    {
        // ...
    }

    public function doStuffOnPostPersist()
    {
        // ...
    }
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

Lifecycle Callbacks Event Argument

Since 2.4 the triggered event is given to the lifecycle-callback.

With the additional argument you have access to the EntityManager and UnitOfWork APIs inside these callback methods.

1
<?php
// ...

class User
{
    public function preUpdate(PreUpdateEventArgs $event)
    {
        if ($event->hasChangedField('username')) {
            // Do something when the username is changed.
        }
    }
}
2
3
4
5
6
7
8
9
10
11
12

Listening and subscribing to Lifecycle Events

Lifecycle event listeners are much more powerful than the simple lifecycle callbacks that are defined on the entity classes. They sit at a level above the entities and allow you to implement re-usable behaviors across different entity classes.

Note that they require much more detailed knowledge about the inner workings of the EntityManager and UnitOfWork. Please read the Implementing Event Listeners section carefully if you are trying to write your own listener.

For event subscribers, there are no surprises. They declare the lifecycle events in their getSubscribedEvents method and provide public methods that expect the relevant arguments.

A lifecycle event listener looks like the following:

1
<?php
use Doctrine\Common\Persistence\Event\LifecycleEventArgs;

class MyEventListener
{
    public function preUpdate(LifecycleEventArgs $args)
    {
        $entity = $args->getObject();
        $entityManager = $args->getObjectManager();

        // perhaps you only want to act on some "Product" entity
        if ($entity instanceof Product) {
            // do something with the Product
        }
    }
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

A lifecycle event subscriber may looks like this:

1
<?php
use Doctrine\ORM\Events;
use Doctrine\Common\EventSubscriber;
use Doctrine\Common\Persistence\Event\LifecycleEventArgs;

class MyEventSubscriber implements EventSubscriber
{
    public function getSubscribedEvents()
    {
        return array(
            Events::postUpdate,
        );
    }

    public function postUpdate(LifecycleEventArgs $args)
    {
        $entity = $args->getObject();
        $entityManager = $args->getObjectManager();

        // perhaps you only want to act on some "Product" entity
        if ($entity instanceof Product) {
            // do something with the Product
        }
    }
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

To register an event listener or subscriber, you have to hook it into the EventManager that is passed to the EntityManager factory:

1
<?php
$eventManager = new EventManager();
$eventManager->addEventListener(array(Events::preUpdate), new MyEventListener());
$eventManager->addEventSubscriber(new MyEventSubscriber());

$entityManager = EntityManager::create($dbOpts, $config, $eventManager);
2
3
4
5
6

You can also retrieve the event manager instance after the EntityManager was created:

1
<?php
$entityManager->getEventManager()->addEventListener(array(Events::preUpdate), new MyEventListener());
$entityManager->getEventManager()->addEventSubscriber(new MyEventSubscriber());
2
3

Implementing Event Listeners

This section explains what is and what is not allowed during specific lifecycle events of the UnitOfWork. Although you get passed the EntityManager in all of these events, you have to follow these restrictions very carefully since operations in the wrong event may produce lots of different errors, such as inconsistent data and lost updates/persists/removes.

For the described events that are also lifecycle callback events the restrictions apply as well, with the additional restriction that (prior to version 2.4) you do not have access to the EntityManager or UnitOfWork APIs inside these events.

1
<?php

use Doctrine\ORM\Event\PreFlushEventArgs;

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

1
<?php
class FlushExampleListener
{
    public function onFlush(OnFlushEventArgs $eventArgs)
    {
        $em = $eventArgs->getEntityManager();
        $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

1
<?php

use Doctrine\ORM\Event\PostFlushEventArgs;

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

1
<?php
class NeverAliceOnlyBobListener
{
    public function preUpdate(PreUpdateEventArgs $eventArgs)
    {
        if ($eventArgs->getEntity() instanceof User) {
            if ($eventArgs->hasChangedField('name') && $eventArgs->getNewValue('name') == 'Alice') {
                $eventArgs->setNewValue('name', 'Bob');
            }
        }
    }
}
2
3
4
5
6
7
8
9
10
11
12

1
<?php
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

Entity listeners

An entity listener is a lifecycle listener class used for an entity.

• The entity listener's mapping may be applied to an entity class or mapped superclass.
• An entity listener is defined by mapping the entity class with the corresponding mapping.

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

1
<?php
// 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

1
<?php
class MyEntityListenerResolver extends \Doctrine\ORM\Mapping\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::create(.., $configurations, ..);
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

Load ClassMetadata Event

When the mapping information for an entity is read, it is populated in to a ClassMetadataInfo instance. You can hook in to this process and manipulate the instance.

1
<?php
$test = new TestEvent();
$metadataFactory = $em->getMetadataFactory();
$evm = $em->getEventManager();
$evm->addEventListener(Events::loadClassMetadata, $test);

class TestEvent
{
    public function loadClassMetadata(\Doctrine\ORM\Event\LoadClassMetadataEventArgs $eventArgs)
    {
        $classMetadata = $eventArgs->getClassMetadata();
        $fieldMapping = array(
            'fieldName' => 'about',
            'type' => 'string',
            'length' => 255
        );
        $classMetadata->mapField($fieldMapping);
    }
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19