From 610295f875bcde46b61c95ca9b5d84a23d0bf9f6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Francesc=20Ros=C3=A0s?= <francescrosasbosque@gmail.com>
Date: Sun, 8 Jul 2012 21:30:00 +0200
Subject: [PATCH] Document preFlush and postFlush events

---
 en/reference/events.rst | 46 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/en/reference/events.rst b/en/reference/events.rst
index dc4f40fe0..dac8ce557 100644
--- a/en/reference/events.rst
+++ b/en/reference/events.rst
@@ -163,9 +163,13 @@ the life-time of their registered entities.
 -  loadClassMetadata - The loadClassMetadata event occurs after the
    mapping metadata for a class has been loaded from a mapping source
    (annotations/xml/yaml).
+-  preFlush - The preFlush event occurs at the very beginning of a flush 
+   operation. This event is not a lifecycle callback.
 -  onFlush - The onFlush event occurs after the change-sets of all
    managed entities are computed. This event is not a lifecycle
    callback.
+-  postFlush - The postFlush event occurs at the end of a flush operation. This
+   event is not a lifecycle callback.
 -  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.
@@ -420,6 +424,27 @@ 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.
 
+preFlush
+~~~~~~~~
+
+``preFlush`` is called at ``EntityManager#flush()`` before 
+anything else. ``EntityManager#flush()`` can be called safely 
+inside its listeners.
+
+.. code-block:: php
+
+    <?php
+
+    use Doctrine\ORM\Event\PreFlushEventArgs;
+
+    class PreFlushExampleListener
+    {
+        public function preFlush(PreFlushEventArgs $args)
+        {
+            // ...
+        }
+    }
+
 onFlush
 ~~~~~~~
 
@@ -483,6 +508,27 @@ The following restrictions apply to the onFlush event:
    affected entity. This can be done by either calling
    ``$unitOfWork->recomputeSingleEntityChangeSet($classMetadata, $entity)``.
 
+postFlush
+~~~~~~~~~
+
+``postFlush`` is called at the end of ``EntityManager#flush()`` before the 
+lists of scheduled changes are cleared. ``EntityManager#flush()`` can be 
+called safely inside its listeners.
+
+.. code-block:: php
+
+    <?php
+
+    use Doctrine\ORM\Event\PostFlushEventArgs;
+
+    class PostFlushExampleListener
+    {
+        public function postFlush(PostFlushEventArgs $args)
+        {
+            // ...
+        }
+    }
+
 preUpdate
 ~~~~~~~~~