9. Events¶
Doctrine ORM features a lightweight event system that is part of the Common package. Doctrine uses it to dispatch system events, mainly lifecycle events. You can also use it for your own custom events.
9.1. 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.
<?php
$evm = new EventManager();
Now we can add some event listeners to the $evm. Let’s create a
TestEvent class to play around with.
<?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);
Events can be dispatched by using the dispatchEvent() method.
<?php
$evm->dispatchEvent(TestEvent::preFoo);
$evm->dispatchEvent(TestEvent::postFoo);
You can easily remove a listener with the removeEventListener()
method.
<?php
$evm->removeEventListener(array(self::preFoo, self::postFoo), $this);
The Doctrine ORM 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.
<?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);
Note
The array to return in the getSubscribedEvents method is a simple array
with the values being the event names. The subscriber must have a method
that is named exactly like the event.
Now when you dispatch an event, any event subscribers will be notified for that event.
<?php
$evm->dispatchEvent(TestEvent::preFoo);
Now you can test the $eventSubscriber instance to see if the
preFoo() method was invoked.
<?php
if ($eventSubscriber->preFooInvoked) {
echo 'pre foo invoked!';
}
9.1.1. 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
すべてのイベントについて、Lifecycle Event Listener または Subscriber クラスを作成して登録できます
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.
9.2. Events Overview¶
Event イベント |
Dispatched by 発送元 |
Lifecycle Callback LifecycleCallback |
Passed Argument 渡された引数 |
|---|---|---|---|
preRemove |
$em->remove() |
Yes はい |
PreRemoveEventArgs |
ポスト削除 |
$em->flush() |
Yes はい |
PostRemoveEventArgs |
prePersist |
$em->persist() on 初期持続 |
Yes はい |
PrePersistEventArgs |
postPersist |
$em->flush() |
Yes はい |
PostPersistEventArgs |
preUpdate |
$em->flush() |
Yes はい |
PreUpdateEventArgs |
postUpdate |
$em->flush() |
Yes はい |
PostUpdateEventArgs |
postLoad |
Loading from database データベースから読み込み中 |
Yes はい |
PostLoadEventArgs |
loadClassMetadata |
Loading of mapping metadata マッピングメタデータの読み込み |
No いいえ |
LoadClassMetadataEventArgs |
onClassMetadataNotFound |
マッピング例外 |
No いいえ |
OnClassMetadataNotFoundEventArgs OnClassMetadataNotFoundEventArgs |
プレフラッシュ |
$em->flush() |
Yes はい |
PreFlushEventArgs |
オンフラッシュ |
$em->flush() |
No いいえ |
OnFlushEventArgs |
ポストフラッシュ |
$em->flush() |
No いいえ |
PostFlushEventArgs |
onClear |
$em->clear() |
No いいえ |
OnClearEventArgs |
9.2.1. 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.
EventSubscriber 内の各メソッドは、対応する定数の値にちなんで名付けられています。定数の名前と値が異なる場合、定数を使用する意図に反し、コードの保守が難しくなります。
An example for a correct notation can be found in the example
TestEvent above.
9.3. 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.
Note
Lifecycle Callbacks are not supported for Embeddables.
9.4. Lifecycle Callbacks Event Argument¶
The triggered event is also given to the lifecycle-callback.
With the additional argument you have access to the
EntityManager and UnitOfWork APIs inside these callback methods.
<?php
// ...
class User
{
public function preUpdate(PreUpdateEventArgs $event)
{
if ($event->hasChangedField('username')) {
// Do something when the username is changed.
}
}
}
9.5. 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 classes. 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:
<?php
use Doctrine\ORM\Event\PreUpdateEventArgs;
class MyEventListener
{
public function preUpdate(PreUpdateEventArgs $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
}
}
}
A lifecycle event subscriber may look like this:
<?php
use Doctrine\ORM\Event\PostUpdateEventArgs;
use Doctrine\ORM\Events;
use Doctrine\EventSubscriber;
class MyEventSubscriber implements EventSubscriber
{
public function getSubscribedEvents()
{
return array(
Events::postUpdate,
);
}
public function postUpdate(PostUpdateEventArgs $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
}
}
Note
Lifecycle events are triggered for all entities. It is the responsibility of the listeners and subscribers to check if the entity is of a type it wants to handle.
To register an event listener or subscriber, you have to hook it into the EventManager that is passed to the EntityManager factory:
<?php
use Doctrine\ORM\Events;
$eventManager = new EventManager();
$eventManager->addEventListener([Events::preUpdate], new MyEventListener());
$eventManager->addEventSubscriber(new MyEventSubscriber());
$entityManager = new EntityManager($connection, $config, $eventManager);
You can also retrieve the event manager instance after the EntityManager was created:
<?php
use Doctrine\ORM\Events;
$entityManager->getEventManager()->addEventListener([Events::preUpdate], new MyEventListener());
$entityManager->getEventManager()->addEventSubscriber(new MyEventSubscriber());
9.6. Implementing Event Listeners¶
This section explains what is and what is not allowed during
specific lifecycle events of the UnitOfWork class. Although you get
passed the EntityManager instance 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.
9.6.1. prePersist¶
There are two ways for the prePersist event to be triggered:
One is obviously when you call
EntityManager::persist(). The1 つは明らかに EntityManager::persist() を呼び出すときです。の
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.
シーケンスなどの PrePersist Identity Generator を使用している場合、ID 値は PrePersist イベント内では使用できません。Doctrine will not recognize changes made to relations in a prePersist event. This includes modifications to collections such as additions, removals or replacement.
Doctrine は prePersistevent でリレーションに加えられた変更を認識しません。これには、追加、削除、置換などのコレクションへの変更が含まれます。
9.6.2. 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.
9.6.3. 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.
<?php
use Doctrine\ORM\Event\PreFlushEventArgs;
class PreFlushExampleListener
{
public function preFlush(PreFlushEventArgs $args)
{
// ...
}
}
9.6.4. 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:
<?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) {
}
}
}
The following restrictions apply to the onFlush event:
If you create and persist a new entity in
onFlush, then callingEntityManager::persist()is not enough. You have to execute an additional call to$unitOfWork->computeChangeSet($classMetadata, $entity).onFlush で新しいエンティティを作成して永続化する場合、EntityManager::persist() を呼び出すだけでは不十分です。$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).プリミティブ フィールドまたは関連付けを変更するには、影響を受けるエンティティの変更セットの再計算を明示的にトリガーする必要があります。これは、$unitOfWork->recomputeSingleEntityChangeSet($classMetadata, $entity) を呼び出すことで実行できます。
9.6.5. 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.
<?php
use Doctrine\ORM\Event\PostFlushEventArgs;
class PostFlushExampleListener
{
public function postFlush(PostFlushEventArgs $args)
{
// ...
}
}
9.6.6. 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
UPDATEstatement.UPDATE ステートメント。
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.getEntity() を使用して、実際のエンティティにアクセスできます。getEntityChangeSet()to get a copy of the changeset array. Changes to this returned array do not affect updating.getEntityChangeSet() を使用して変更セット配列のコピーを取得します。この返された配列を変更しても、更新には影響しません。hasChangedField($fieldName)to check if the given field name of the current entity changed.hasChangedField($fieldName) を使用して、現在のエンティティの指定されたフィールド名が変更されたかどうかを確認します。getOldValue($fieldName)andgetNewValue($fieldName)to access the values of a field.フィールドの値にアクセスするには、getOldValue($fieldName) および getNewValue($fieldName) を使用します。setNewValue($fieldName, $value)to change the value of a field to be updated.setNewValue($fieldName, $value) を使用して、更新するフィールドの値を変更します。
A simple example for this event looks like:
<?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');
}
}
}
}
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:
<?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.
}
}
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.渡されたエンティティのフィールドへの変更は、フラッシュ操作によって認識されなくなりました。イベントに渡された計算された変更セットを使用して、プリミティブ フィールド値を変更します。 use$eventArgs->setNewValue($field, $value);上記のアリスからボブへの例のように。Any calls to
EntityManager::persist()orEntityManager::remove(), even in combination with theUnitOfWorkAPI are strongly discouraged and don’t work as expected outside the flush operation.EntityManager::persist() または EntityManager::remove() への呼び出しは、UnitOfWorkAPI と組み合わせた場合でも、強くお勧めできません。フラッシュ操作以外では期待どおりに動作しません。
9.6.7. 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
postUpdateevent occurs after the database update operations to entity data. It is not called for a DQLUPDATEstatement.postUpdate イベントは、エンティティ データに対する databaseupdate 操作の後に発生します。 DQLUPDATE ステートメントでは呼び出されません。The
postPersistevent 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.postPersist イベントは、エンティティが永続化された後にエンティティに対して発生します。これは、データベースの挿入操作の後に呼び出されます。生成された主キーの値は、postPersist イベントで使用できます。The
postRemoveevent 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 DQLDELETEstatement.postRemove イベントは、エンティティが削除された後にエンティティに対して発生します。これは、databasedelete 操作の後に呼び出されます。 DQL DELETE ステートメントでは呼び出されません。
Warning
The postRemove event or any events triggered after an entity removal
can receive an uninitializable proxy in case you have configured an entity to
cascade remove relations. In this case, you should load yourself the proxy in
the associated pre* event.
9.6.8. 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.
Warning
When using Doctrine\ORM\AbstractQuery::toIterable(), postLoad
events will be executed immediately after objects are being hydrated, and therefore
associations are not guaranteed to be initialized. It is not safe to combine
usage of Doctrine\ORM\AbstractQuery::toIterable() and postLoad event
handlers.
9.6.9. 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.
9.7. 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.
エンティティ リスナーは、エンティティ クラスを対応するマッピングでマッピングすることによって定義されます。
9.7.1. 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 Listeneris invoked just to the specified entityイベント リスナーの実装とは異なり、エンティティ リスナーは指定されたエンティティに対してのみ呼び出されます。An entity listener method receives two arguments, the entity instance and the lifecycle event.
エンティティ リスナー メソッドは、エンティティ インスタンスとライフサイクル イベントの 2 つの引数を受け取ります。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 thepreUpdateevent.リスナーのマッピングが指定されていない場合、パーサーは命名規則を使用して一致するメソッドを探します。 preUpdate イベントをリッスンしている場合は、パブリックな preUpdate() メソッドを探します。When a listener mapping is given the parser will not look for any methods using the naming convention.
リスナー マッピングが指定されている場合、パーサーは命名規則を使用してメソッドを検索しません。
<?php
use Doctrine\ORM\Event\PreUpdateEventArgs;
class UserListener
{
public function preUpdate(User $user, PreUpdateEventArgs $event)
{
// Do something on pre update.
}
}
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:
Note
The order of execution of multiple methods for the same event (e.g. multiple @PrePersist) is not guaranteed.
9.7.2. 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\DefaultEntityListenerResolveror implementingDoctrine\ORM\Mapping\EntityListenerResolverDoctrine\ORM\Mapping\DefaultEntityListenerResolver を拡張するか、Doctrine\ORM\Mapping\EntityListenerResolver を実装することで、独自のリゾルバーを実装することもできます。
Specifying an entity listener instance :
<?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);
Implementing your own resolver:
<?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, ..);
9.8. Load ClassMetadata Event¶
loadClassMetadata - The loadClassMetadata event occurs after the
mapping metadata for a class has been loaded from a mapping source
(attributes/annotations/xml/yaml) in to a Doctrine\ORM\Mapping\ClassMetadata instance.
You can hook in to this process and manipulate the instance.
This event is not a lifecycle callback.
<?php
use Doctrine\ORM\Event\LoadClassMetadataEventArgs;
$test = new TestEventListener();
$evm = $em->getEventManager();
$evm->addEventListener(Doctrine\ORM\Events::loadClassMetadata, $test);
class TestEventListener
{
public function loadClassMetadata(LoadClassMetadataEventArgs $eventArgs)
{
$classMetadata = $eventArgs->getClassMetadata();
$fieldMapping = array(
'fieldName' => 'about',
'type' => 'string',
'length' => 255
);
$classMetadata->mapField($fieldMapping);
}
}
If not class metadata can be found, an onClassMetadataNotFound event is dispatched.
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.
9.9. SchemaTool Events¶
It is possible to access the schema metadata during schema changes that are happening in Doctrine\ORM\Tools\SchemaTool.
There are two different events where you can hook in.
9.9.1. 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.
<?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();
}
}
9.9.2. 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.
<?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();
}
}
