Added documentation for preMove and postMove events #20

Merged
merged 3 commits into from Feb 23, 2013

2 participants

@dbu dbu commented on the diff Feb 22, 2013
en/reference/events.rst
@@ -29,6 +29,8 @@ the life-time of their registered documents.
- preFlush - occurs at the very beginning of a flush operation. This event is not a lifecycle callback.
- onFlush - occurs after the change-sets of all managed documents have been computed. This event is not a lifecycle
callback.
+- preMove - occurs before a document is moved to the target path
@dbu
Doctrine member
dbu added a note Feb 22, 2013

please tell that this happens during persisting the move (it does, right? so when caling $dm->flush, not when calling $dm->move?) and please explain in which order the events occur (preFlush preMove postMove onFlush ? )

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@laupiFrpar

I added more explanation at the end of the file.
I hope that is clear :)

@dantleech dantleech commented on the diff Feb 22, 2013
en/reference/events.rst
@@ -144,3 +146,18 @@ Listening to Lifecycle Events
-----------------------------
This works exactly the same as with the `ORM events <http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/events.html>`_.
+
+Move events
+-----------
+
+When I move a document, the document is not be modified, except the ID.
+The preFlush and onFlush events may modify the document before moving the document.
+
+When $dm->flush is calling after $dm->move(), the order of events is:
+
+1. preFlush
+2. onFlush
+3. preMove
+4. postMove
+5. postFlush
+

I would use a .. note:: markup for the first paragraph, and add it after the other .. note:: above, and I think then rename this section to "Persistance event order". What do you think?

Ok I updated this document

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@dbu dbu commented on the diff Feb 22, 2013
en/reference/events.rst
@@ -37,6 +39,10 @@ the life-time of their registered documents.
See the `Documentation of DoctrinePHPCRBundle <http://github.com/doctrine/DoctrinePHPCRBundle>`_
for more information.
+.. note::
+
+ When I move a document, the document is not be modified, except the ID.
@dbu
Doctrine member
dbu added a note Feb 22, 2013

can we reformulate that to The document is moved during the flush, after field changes have been written. If the move event handlers change properties of the document, those changes are not considered in this flush anymore.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@dantleech dantleech commented on the diff Feb 22, 2013
en/reference/events.rst
@@ -144,3 +150,15 @@ Listening to Lifecycle Events
-----------------------------
This works exactly the same as with the `ORM events <http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/events.html>`_.
+
+Persistance event order
+-----------------------
+
+When $dm->flush is calling after $dm->move(), the order of events is:

This is the generic event order no? i.e. events will happen in this order and it doesn't matter which method you call, so I think something like "Events are fired in the following order when you call $dm->flush' would be all that is needed. (you can put two "backquotes around inline code blocks like that, see : http://sphinx-doc.org/rest.html#inline-markup)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@dbu dbu merged commit c4bd664 into doctrine:master Feb 23, 2013
@dbu
Doctrine member

thanks for the doc. also did some cleanup ba8b505 - and noticed that we might want annotations to allow to use the move events as lifecycle callbacks as well...

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment