manual/docs/en/event-listeners.txt

@@ -1,13 +1,11 @@
 ++ Introduction
 
-*** THIS CHAPTER AND THE CODE IT REFERS TO IS UNDER CONSTRUCTION ***
-
-
 Doctrine provides flexible event listener architecture that not only allows listening for different events but also for altering the execution of the listened methods.
 
-There are several different listeners and hooks for various Doctrine components. Listeners are separate classes where as hooks are empty template methods which are defined in the base class.
+There are several different listeners and hooks for various Doctrine components. Listeners are separate classes whereas hooks are empty template methods within the listened class.
+
+Hooks are simpler than eventlisteners but they lack the separation of different aspects. An example of using Doctrine_Record hooks:
 
-An example of using Doctrine_Record hooks:
 <code type="php">
 class Blog extends Doctrine_Record 
 {
@@ -32,6 +30,11 @@ $blog->save();
 
 $blog->created; // 2007-06-20 (format: YYYY-MM-DD)
 </code>
+
+Each listener and hook method takes one parameter Doctrine_Event object. Doctrine_Event object holds information about the event in question and can alter the execution of the listened method.
+
+For the purposes of this documentation many method tables are provided with column named 'params' indicating names of the parameters that an event object holds on given event. For example the preCreateSavepoint event has one parameter the name of the created savepoint, which is quite intuitively named as savepoint.
+
 ++ Connection listeners    
 
 Connection listeners are used for listening the methods of Doctrine_Connection and its modules (such as Doctrine_Transaction). All listener methods take one argument Doctrine_Event which holds information about the listened event.
@@ -99,41 +102,88 @@ $conn->addListener(new MyLogger());
 
 +++ Transaction listeners
 ||~ Methods     ||~ Listens ||~ Params ||
-|| preTransactionBegin() || Doctrine_Transaction::beginTransaction() || ||
-|| postTransactionBegin() || Doctrine_Transaction::beginTransaction() || ||
-|| preTransactionRollback() || Doctrine_Transaction::rollback() || ||
-|| postTransactionRollback() || Doctrine_Transaction::rollback() || ||
-|| preTransactionCommit() || Doctrine_Transaction::commit() || ||
-|| postTransactionCommit() || Doctrine_Transaction::commit() || ||
-|| preCreateSavepoint() || Doctrine_Transaction::createSavepoint() || savepoint ||
-|| postCreateSavepoint() || Doctrine_Transaction::createSavepoint() || savepoint ||
-|| preRollbackSavepoint() || Doctrine_Transaction::rollbackSavepoint() || savepoint ||
-|| postRollbackSavepoint() || Doctrine_Transaction::rollbackSavepoint() || savepoint ||
-|| preReleaseSavepoint() || Doctrine_Transaction::releaseSavepoint() || savepoint ||
-|| postReleaseSavepoint() || Doctrine_Transaction::releaseSavepoint() || savepoint ||
+|| preTransactionBegin(Doctrine_Event $event) || Doctrine_Transaction::beginTransaction() || ||
+|| postTransactionBegin(Doctrine_Event $event) || Doctrine_Transaction::beginTransaction() || ||
+|| preTransactionRollback(Doctrine_Event $event) || Doctrine_Transaction::rollback() || ||
+|| postTransactionRollback(Doctrine_Event $event) || Doctrine_Transaction::rollback() || ||
+|| preTransactionCommit(Doctrine_Event $event) || Doctrine_Transaction::commit() || ||
+|| postTransactionCommit(Doctrine_Event $event) || Doctrine_Transaction::commit() || ||
+|| preCreateSavepoint(Doctrine_Event $event) || Doctrine_Transaction::createSavepoint() || savepoint ||
+|| postCreateSavepoint(Doctrine_Event $event) || Doctrine_Transaction::createSavepoint() || savepoint ||
+|| preRollbackSavepoint(Doctrine_Event $event) || Doctrine_Transaction::rollbackSavepoint() || savepoint ||
+|| postRollbackSavepoint(Doctrine_Event $event) || Doctrine_Transaction::rollbackSavepoint() || savepoint ||
+|| preReleaseSavepoint(Doctrine_Event $event) || Doctrine_Transaction::releaseSavepoint() || savepoint ||
+|| postReleaseSavepoint(Doctrine_Event $event) || Doctrine_Transaction::releaseSavepoint() || savepoint ||
+
+<code type="php">
+class MyTransactionListener extends Doctrine_EventListener
+{
+    public function preTransactionBegin(Doctrine_Event $event)
+    {
+        print 'beginning transaction... ';
+    }
+
+    public function preTransactionRollback(Doctrine_Event $event)
+    {
+        print 'rolling back transaction... ';
+    }
+}
+
+</code>
 
 +++ Query execution listeners
 
 ||~ Methods     ||~ Listens ||~ Params ||
-|| prePrepare() || Doctrine_Connection::prepare() || query ||
-|| postPrepare() || Doctrine_Connection::prepare() || query ||
-|| preExec() || Doctrine_Connection::exec() || query ||
-|| postExec() || Doctrine_Connection::exec() || query, rows ||
-|| preStmtExecute() || Doctrine_Connection_Statement::execute() || query ||
-|| postStmtExecute() || Doctrine_Connection_Statement::execute() || query ||
-|| preExecute() || Doctrine_Connection::execute() * || query ||
-|| postExecute() || Doctrine_Connection::execute() * || query ||
-|| preFetch() || Doctrine_Connection::fetch() || query, data ||
-|| postFetch() || Doctrine_Connection::fetch() || query, data ||
-|| preFetchAll() || Doctrine_Connection::fetchAll() || query, data ||
-|| postFetchAll() || Doctrine_Connection::fetchAll() || query, data ||
+|| prePrepare(Doctrine_Event $event) || Doctrine_Connection::prepare() || query ||
+|| postPrepare(Doctrine_Event $event) || Doctrine_Connection::prepare() || query ||
+|| preExec(Doctrine_Event $event) || Doctrine_Connection::exec() || query ||
+|| postExec(Doctrine_Event $event) || Doctrine_Connection::exec() || query, rows ||
+|| preStmtExecute(Doctrine_Event $event) || Doctrine_Connection_Statement::execute() || query ||
+|| postStmtExecute(Doctrine_Event $event) || Doctrine_Connection_Statement::execute() || query ||
+|| preExecute(Doctrine_Event $event) || Doctrine_Connection::execute() * || query ||
+|| postExecute(Doctrine_Event $event) || Doctrine_Connection::execute() * || query ||
+|| preFetch(Doctrine_Event $event) || Doctrine_Connection::fetch() || query, data ||
+|| postFetch(Doctrine_Event $event) || Doctrine_Connection::fetch() || query, data ||
+|| preFetchAll(Doctrine_Event $event) || Doctrine_Connection::fetchAll() || query, data ||
+|| postFetchAll(Doctrine_Event $event) || Doctrine_Connection::fetchAll() || query, data ||
+
+* preExecute() and postExecute() only get invoked when Doctrine_Connection::execute() is being called without prepared statement parameters. Otherwise Doctrine_Connection::execute() invokes prePrepare, postPrepare, preStmtExecute and postStmtExecute.
 
-* preExecute() and postExecute() only get invoked when Doctrine_Connection::execute() is called without prepared statement parameters. Otherwise Doctrine_Connection::execute() invokes prePrepare, postPrepare, preStmtExecute and postStmtExecute.
 
 
 ++ Query listeners
-+++ preHydrate, postHydrate
-+++ preBuildQuery, postBuildQuery
+
+The query listeners can be used for listening the DQL query building and resultset hydration procedures. Couple of methods exist for listening the hydration procedure: preHydrate and postHydrate.
+
+If you set the hydration listener on connection level the code within the preHydrate and postHydrate blocks will be invoked by all components within a multi-component resultset. However if you add a similar listener on table level it only gets invoked when the data of that table is being hydrated.
+
+Consider we have a class called User with the following fields: firstname, lastname and age. In the following example we create a listener that always builds a generated field called fullname based on firstname and lastname fields.
+
+<code type="php">
+class HydrationListener extends Doctrine_Record_Listener
+{
+    public function preHydrate(Doctrine_Event $event)
+    {
+        $data = $event->data;
+
+        $data['fullname'] = $data['firstname'] . ' ' . $data['lastname'];
+    }
+}
+</code>
+
+Now all we need to do is attach this listener to the User record and fetch some users.
+
+<code type="php">
+$user = new User();
+$user->addListener(new HydrationListener());
+
+$users = Doctrine_Query::create()->from('User');
+
+foreach ($users as $user) {
+    print $user->fullname;
+}
+</code>
+
 ++ Record listeners
 
 Doctrine_Record provides listeners very similar to Doctrine_Connection. You can set the listeners at global, connection and record(=table) level.
@@ -141,16 +191,16 @@ Doctrine_Record provides listeners very similar to Doctrine_Connection. You can
 Here is a list of all available listener methods:
 
 ||~ Methods     ||~ Listens ||
-|| preSave() || Doctrine_Record::save() ||
-|| postSave() || Doctrine_Record::save() ||
-|| preUpdate() || Doctrine_Record::save() when the record state is DIRTY ||
-|| postUpdate() || Doctrine_Record::save() when the record state is DIRTY ||
-|| preInsert() || Doctrine_Record::save() when the record state is TDIRTY ||
-|| postInsert() || Doctrine_Record::save() when the record state is TDIRTY ||
-|| preDelete() || Doctrine_Record::delete() ||
-|| postDelete() || Doctrine_Record::delete() ||
-|| preValidate() || Doctrine_Validator::validate() ||
-|| postValidate() || Doctrine_Validator::validate() ||
+|| preSave(Doctrine_Event $event) || Doctrine_Record::save() ||
+|| postSave(Doctrine_Event $event) || Doctrine_Record::save() ||
+|| preUpdate(Doctrine_Event $event) || Doctrine_Record::save() when the record state is DIRTY ||
+|| postUpdate(Doctrine_Event $event) || Doctrine_Record::save() when the record state is DIRTY ||
+|| preInsert(Doctrine_Event $event) || Doctrine_Record::save() when the record state is TDIRTY ||
+|| postInsert(Doctrine_Event $event) || Doctrine_Record::save() when the record state is TDIRTY ||
+|| preDelete(Doctrine_Event $event) || Doctrine_Record::delete() ||
+|| postDelete(Doctrine_Event $event) || Doctrine_Record::delete() ||
+|| preValidate(Doctrine_Event $event) || Doctrine_Validator::validate() ||
+|| postValidate(Doctrine_Event $event) || Doctrine_Validator::validate() ||
 
 Just like with connection listeners there are three ways of defining a record listener: by extending Doctrine_Record_Listener, by implement Doctrine_Record_Listener_Interface or by implementing Doctrine_Overloadable. In the following we'll create a global level listener by implementing Doctrine_Overloadable:
 <code type="php">
@@ -259,10 +309,9 @@ class Blog extends Doctrine_Record
 }
 </code>
 
-++ Listening events
 ++ Chaining listeners
 
-All different event listeners in Doctrine allow chaining. This means that more than one listener can be attached for listening the same methods. The following example attaches two listeners for given connection:
+Doctrine allows chaining of different eventlisteners. This means that more than one listener can be attached for listening the same events. The following example attaches two listeners for given connection:
 
 <code type="php">
 // here Debugger and Logger both inherit Doctrine_EventListener