diff --git a/docs/en/reference/events.rst b/docs/en/reference/events.rst index c37c0fc73..f315f66b1 100644 --- a/docs/en/reference/events.rst +++ b/docs/en/reference/events.rst @@ -205,12 +205,12 @@ 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 + 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, +The EventArgs instance received by the listener gives access to the entity, EntityManager and other relevant data. .. note:: @@ -225,9 +225,9 @@ 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 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. @@ -280,7 +280,7 @@ specific to a particular entity class's lifecycle. } Note that the methods set as lifecycle callbacks need to be public and, -when using these annotations, you have to apply the +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 @@ -299,7 +299,7 @@ can do it with the following. postPersist: [ doStuffOnPostPersist ] 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 +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: @@ -325,11 +325,11 @@ XML would look something like this: 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 +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()``, +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. @@ -389,7 +389,7 @@ 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 +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 @@ -492,7 +492,7 @@ 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 +that (prior to version 2.4) you do not have access to the EntityManager or UnitOfWork APIs inside these events. prePersist @@ -517,11 +517,9 @@ 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. -- Doctrine will not recognize changes made to relations in a prePersist - event called by "reachability" through a cascade persist unless you - use the internal ``UnitOfWork`` API. We do not recommend such - operations in the persistence by reachability context, so do - this at your own risk and possibly supported by unit-tests. +- Doctrine will not recognize changes made to relations in a prePersist + event. This includes modifications to + collections such as additions, removals or replacement. preRemove ~~~~~~~~~ @@ -715,7 +713,7 @@ Restrictions for this event: 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 + the event to modify primitive field values, e.g. use ``$eventArgs->setNewValue($field, $value);`` as in the Alice to Bob example above. - Any calls to ``EntityManager#persist()`` or ``EntityManager#remove()``, even in combination with the UnitOfWork @@ -787,7 +785,7 @@ An ``Entity Listener`` could be any class, by default it should be a class with - 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. - 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, +- 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 the ``preUpdate`` event. - When a listener mapping is given the parser will not look for any methods using the naming convention.