diff --git a/docs/en/reference/events.rst b/docs/en/reference/events.rst
index f2f112f38..554e4e1db 100644
--- a/docs/en/reference/events.rst
+++ b/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
+
+
+
+
+
+
+
+
+
+ .. 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
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ .. 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
+
+ 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
+
+ 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
------------------------