Permalink
Browse files

Docs for Entity Listener and Entity Listener Resolver

  • Loading branch information...
FabioBatSilva committed Feb 2, 2013
1 parent 76c4be1 commit 7764ed9a8b6df0c52651c398890f13e704f5a354
Showing with 202 additions and 3 deletions.
  1. +202 −3 docs/en/reference/events.rst
@@ -196,9 +196,7 @@ listeners:
- Lifecycle Callbacks are methods on the entity classes that are
- called when the event is triggered. They receive absolutely no
- arguments and are specifically designed to allow changes inside the
- entity classes state.
+ called when the event is triggered. They receives some kind of ``EventArgs``.
- Lifecycle Event Listeners are classes with specific callback
methods that receives some kind of ``EventArgs`` instance which
give access to the entity, EntityManager or other relevant data.
@@ -337,6 +335,7 @@ the value is the event type. The allowed event types are the ones
listed in the previous Lifecycle Events section.
.. versionadded:: 2.4
+
Lifecycle Callbacks Event Argument
-----------------------------------
@@ -650,6 +649,206 @@ postLoad
This event is called after an entity is constructed by the
EntityManager.
+Entity listeners
+----------------
+
+An entity listeners is a lifecycle listener classes used for an entity.
+
+- The entity listeners 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.
+
+.. configuration-block::
+
+ .. code-block:: php
+
+ <?php
+ namespace MyProject\Entity;
+
+ /** @Entity @EntityListeners({"UserListener"}) */
+ class User
+ {
+ // ....
+ }
+ .. code-block:: xml
+
+ <doctrine-mapping>
+ <entity name="MyProject\Entity\User">
+ <entity-listeners>
+ <entity-listener class="UserListener"/>
+ </entity-listeners>
+ <!-- .... -->
+ </entity>
+ </doctrine-mapping>
+ .. code-block:: yaml
+
+ MyProject\Entity\User:
+ type: entity
+ entityListeners:
+ UserListener:
+ # ....
+
+.. _reference-entity-listeners:
+
+Entity listeners class
+~~~~~~~~~~~~~~~~~~~~~~
+
+An ``Entity Listener`` could be any class, by default it should be a class with a no-arg constructor.
+
+- Different from :ref:`reference-events-implementing-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.
+- A callback method could be defined by naming convention or specifying a method mapping.
+- When the listener mapping is not given the parser will lookup for methods that match with the naming convention.
+- When the listener mapping is given the parser won't lookup for any naming convention.
+
+.. code-block:: php
+
+ <?php
+ class UserListener
+ {
+ public function preUpdate(User $user, PreUpdateEventArgs $event)
+ {
+ // Do something on pre update.
+ }
+ }
+
+To define a specific event listener method
+you should map the listener method using the event type mapping.
+
+.. configuration-block::
+
+ .. code-block:: php
+
+ <?php
+ class UserListener
+ {
+ /** @PrePersist */
+ public function prePersistHandler(User $user, LifecycleEventArgs $event) { // ... }
+
+ /** @PostPersist */
+ public function postPersistHandler(User $user, LifecycleEventArgs $event) { // ... }
+
+ /** @PreUpdate */
+ public function preUpdateHandler(User $user, PreUpdateEventArgs $event) { // ... }
+
+ /** @PostUpdate */
+ public function postUpdateHandler(User $user, LifecycleEventArgs $event) { // ... }
+
+ /** @PostRemove */
+ public function postRemoveHandler(User $user, LifecycleEventArgs $event) { // ... }
+
+ /** @PreRemove */
+ public function preRemoveHandler(User $user, LifecycleEventArgs $event) { // ... }
+
+ /** @PreFlush */
+ public function preFlushHandler(User $user, PreFlushEventArgs $event) { // ... }
+
+ /** @PostLoad */
+ public function postLoadHandler(User $user, LifecycleEventArgs $event) { // ... }
+ }
+ .. code-block:: xml
+
+ <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>
+ .. code-block:: yaml
+
+ MyProject\Entity\User:
+ type: entity
+ UserListener:
+ preFlush: [preFlushHandler]
+ postLoad: [postLoadHandler]
+
+ postPersist: [postPersistHandler]
+ prePersist: [prePersistHandler]
+
+ postUpdate: [postUpdateHandler]
+ preUpdate: [preUpdateHandler]
+
+ postRemove: [postRemoveHandler]
+ preRemove: [preRemoveHandler]
+ # ....
+
+
+
+Entity listeners resolver
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+Doctrine invoke the listener resolver to get the listener instance.
+
+- An 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 :
+
+.. code-block:: php
+
+ <?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);
+
+Implementing your own resolver :
+
+.. code-block:: php
+
+ <?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.
+ $em->getConfiguration()->setEntityListenerResolver($container->get('my_resolver'));
+
Load ClassMetadata Event
------------------------

0 comments on commit 7764ed9

Please sign in to comment.