Doctrine: Events reference

In a nutshell

Doctrine ORM provides a lightweight event system that lets you register custom event listeners / subscribers that hook into various lifecycle events (e.g., prePersist, postPersist, preUpdate, etc).

List of events

Event	Dispatched by	Lifecycle Callback	Passed Argument
preRemove	$em->remove()	Yes	LifecycleEventArgs
postRemove	$em->flush()	Yes	LifecycleEventArgs
prePersist	$em->persist() on initial persist	Yes	LifecycleEventArgs
postPersist	$em->flush()	Yes	LifecycleEventArgs
preUpdate	$em->flush()	Yes	PreUpdateEventArgs
postUpdate	$em->flush()	Yes	LifecycleEventArgs
postLoad	Loading from database	Yes	LifecycleEventArgs
loadClassMetadata	Loading of mapping metadata	No	LoadClassMetadataEventArgs
onClassMetadataNotFound	MappingException	No	OnClassMetadataNotFoundEventArgs
preFlush	$em->flush()	Yes	PreFlushEventArgs
onFlush	$em->flush()	No	OnFlushEventArgs
postFlush	$em->flush()	No	PostFlushEventArgs
onClear	$em->clear()	No	OnClearEventArgs

prePersist

Called when:

1. You explicitly call EntityManager:persist(). Also called for cascaded associations.
2. Inside the flush() method if the entity is a new entity (either standalone or as an association).

prePersist is only invoked on initial persist of an entity, not on future updates.

postPersist

Called after the entity has been made persistent. Invoked after the database insert operations. Generated primary key values are available in the postPersist event.

onFlush

Called inside EntityManager::flush() after all the changes to managed entities and their associations have been computed. The onFlush event has access to the:

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

Here’s an example usage of the onFlush event:

<?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) {

        }
    }
}

Recipes

Register event listeners

<?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);

Dispatch events

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

Create event subscriber

You can also write your event handling logic in the form of event subscribers that implement the \Doctrine\Common\EventSubscriber interface.

<?php
use Doctrine\Common\EventSubscriber;

class TestEventSubscriber implements EventSubscriber
{
    public $preFooInvoked = false;

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

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

$eventSubscriber = new TestEventSubscriber();
$evm->addEventSubscriber($eventSubscriber);

The getSubscribedEvents() method must return an array where each value represents the event name and a method (named exactly the same) that subscribes to that event.

Sources

• Events – Doctrine docs
• Doctrine\ORM\EntityManager