*** 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.
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.
+++ Creating a new listener
There are three different ways of defining a listener. First you can create a listener by making a class that inherits Doctrine_EventListener:
<code type="php">
class MyListener extends Doctrine_EventListener
{
public function preExec(Doctrine_Event $event)
{
}
}
</code>
Note that by declaring a class that extends Doctrine_EventListener you don't have to define all the methods within the Doctrine_EventListener_Interface. This is due to a fact that Doctrine_EventListener already has empty skeletons for all these methods.
Sometimes it may not be possible to define a listener that extends Doctrine_EventListener (you might have a listener that inherits some other base class). In this case you can make it implement Doctrine_EventListener_Interface.
<code type="php">
class MyListener implements Doctrine_EventListener_Interface
{
// notice: all listener methods must be defined here
// (otherwise PHP throws fatal error)
public function preExec(Doctrine_Event $event)
{ }
public function postExec(Doctrine_Event $event)
{ }
// ...
}
</code>
The third way of creating a listener is a very elegant one. You can make a class that implements Doctrine_Overloadable. This interface has only one method: __call(), which can be used for catching *all* the events.
<code type="php">
class MyDebugger implements Doctrine_Overloadable
{
public function __call($methodName, $args)
{
print $methodName . ' called !';
}
}
</code>
+++ Attaching listeners
You can attach the listeners to a connection with setListener().
<code type="php">
$conn->setListener(new MyDebugger());
</code>
If you need to use multiple listeners you can use addListener().
|| preFetch() || Doctrine_Connection::fetch() || query, data ||
|| postFetch() || Doctrine_Connection::fetch() || query, data ||
|| preFetchAll() || Doctrine_Connection::fetchAll() || query, data ||
|| postFetchAll() || Doctrine_Connection::fetchAll() || query, data ||
* 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
++ Record listeners
Doctrine_Record provides listeners very similar to Doctrine_Connection. You can set the listeners at global, connection and record(=table) level.
Here is a list of all availible 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 ||
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">
class Logger extends Doctrine_Overloadable
{
public function __call($m, $a)
{
print 'catched event ' . $m;
// do some logging here...
}
}
</code>
Attaching the listener to manager is easy:
<code type="php">
$manager->addRecordListener(new Logger());
</code>
Note that by adding a manager level listener it affects on all connections and all tables / records within these connections. In the following we create a connection level listener:
<code type="php">
class Debugger extends Doctrine_Record_Listener
{
public function preInsert(Doctrine_Event $event)
{
print 'inserting a record ...';
}
public function preUpdate(Doctrine_Event $event)
{
print 'updating a record...';
}
}
</code>
Attaching the listener to a connection is as easy as:
<code type="php">
$conn->addRecordListener(new Debugger());
</code>
Many times you want the listeners to be table specific so that they only apply on the actions on that given table. Here is an example:
<code type="php">
class Debugger extends Doctrine_Record_Listener
{
public function postDelete(Doctrine_Event $event)
{
print 'deleted ' . $event->getInvoker()->id;
}
}
</code>
Attaching this listener to given table can be done as follows:
<code type="php">
class MyRecord extends Doctrine_Record
{
public function setTableDefinition()
{
// some definitions
}
public function setUp()
{
$this->addListener(new Debugger());
}
}
</code>
++ Record hooks
||~ Methods ||~ Listens ||
|| preSave($event) || Doctrine_Record::save() ||
|| postSave($event) || Doctrine_Record::save() ||
|| preUpdate($event) || Doctrine_Record::save() when the record state is DIRTY ||
|| postUpdate($event) || Doctrine_Record::save() when the record state is DIRTY ||
|| preInsert($event) || Doctrine_Record::save() when the record state is TDIRTY ||
|| postInsert($event) || Doctrine_Record::save() when the record state is TDIRTY ||
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:
<code type="php">
// here Debugger and Logger both inherit Doctrine_EventListener
$conn->addListener(new Debugger());
$conn->addListener(new Logger());
</code>
++ The Event object
+++ Getting the invoker
You can get the object that invoked the event by calling getInvoker():
<code type="php">
class MyListener extends Doctrine_EventListener
{
public function preExec(Doctrine_Event $event)
{
$event->getInvoker(); // Doctrine_Connection
}
}
</code>
+++ Event codes
Doctrine_Event uses constants as event codes. Above is the list of all availible event constants:
The method getInvoker() returns the object that invoked the given event. For example for event Doctrine_Event::CONN_QUERY the invoker is a Doctrine_Connection object. Example:
<code type="php">
class MyRecord extends Doctrine_Record
{
public function preUpdate(Doctrine_Event $event)
{
$event->getInvoker(); // Object(MyRecord)
}
}
</code>
+++ skipOperation()
Doctrine_Event provides many methods for altering the execution of the listened method as well as for altering the behaviour of the listener chain.
For some reason you may want to skip the execution of the listened method. It can be done as follows (note that preExec could be any listener method):
<code type="php">
class MyListener extends Doctrine_EventListener
{
public function preExec(Doctrine_Event $event)
{
// some business logic, then:
$event->skipOperation();
}
}
</code>
+++ skipNextListener()
When using a chain of listeners you might want to skip the execution of the next listener. It can be achieved as follows:
<code type="php">
class MyListener extends Doctrine_EventListener
{
public function preExec(Doctrine_Event $event)
{
// some business logic, then:
$event->skipNextListener();
}
}
</code>
++ 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.
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.
+++ Creating a new listener
There are three different ways of defining a listener. First you can create a listener by making a class that inherits Doctrine_EventListener:
<code type="php">
class MyListener extends Doctrine_EventListener
{
public function preExec(Doctrine_Event $event)
{
}
}
</code>
Note that by declaring a class that extends Doctrine_EventListener you don't have to define all the methods within the Doctrine_EventListener_Interface. This is due to a fact that Doctrine_EventListener already has empty skeletons for all these methods.
Sometimes it may not be possible to define a listener that extends Doctrine_EventListener (you might have a listener that inherits some other base class). In this case you can make it implement Doctrine_EventListener_Interface.
<code type="php">
class MyListener implements Doctrine_EventListener_Interface
{
// notice: all listener methods must be defined here
// (otherwise PHP throws fatal error)
public function preExec(Doctrine_Event $event)
{ }
public function postExec(Doctrine_Event $event)
{ }
// ...
}
</code>
The third way of creating a listener is a very elegant one. You can make a class that implements Doctrine_Overloadable. This interface has only one method: __call(), which can be used for catching *all* the events.
<code type="php">
class MyDebugger implements Doctrine_Overloadable
{
public function __call($methodName, $args)
{
print $methodName . ' called !';
}
}
</code>
+++ Attaching listeners
You can attach the listeners to a connection with setListener().
<code type="php">
$conn->setListener(new MyDebugger());
</code>
If you need to use multiple listeners you can use addListener().
|| preFetch() || Doctrine_Connection::fetch() || query, data ||
|| postFetch() || Doctrine_Connection::fetch() || query, data ||
|| preFetchAll() || Doctrine_Connection::fetchAll() || query, data ||
|| postFetchAll() || Doctrine_Connection::fetchAll() || query, data ||
* 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
++ Record listeners
Doctrine_Record provides listeners very similar to Doctrine_Connection. You can set the listeners at global, connection and record(=table) level.
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 ||
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">
class Logger extends Doctrine_Overloadable
{
public function __call($m, $a)
{
print 'catched event ' . $m;
// do some logging here...
}
}
</code>
Attaching the listener to manager is easy:
<code type="php">
$manager->addRecordListener(new Logger());
</code>
Note that by adding a manager level listener it affects on all connections and all tables / records within these connections. In the following we create a connection level listener:
<code type="php">
class Debugger extends Doctrine_Record_Listener
{
public function preInsert(Doctrine_Event $event)
{
print 'inserting a record ...';
}
public function preUpdate(Doctrine_Event $event)
{
print 'updating a record...';
}
}
</code>
Attaching the listener to a connection is as easy as:
<code type="php">
$conn->addRecordListener(new Debugger());
</code>
Many times you want the listeners to be table specific so that they only apply on the actions on that given table. Here is an example:
<code type="php">
class Debugger extends Doctrine_Record_Listener
{
public function postDelete(Doctrine_Event $event)
{
print 'deleted ' . $event->getInvoker()->id;
}
}
</code>
Attaching this listener to given table can be done as follows:
<code type="php">
class MyRecord extends Doctrine_Record
{
public function setTableDefinition()
{
// some definitions
}
public function setUp()
{
$this->addListener(new Debugger());
}
}
</code>
++ Record hooks
||~ Methods ||~ Listens ||
|| preSave($event) || Doctrine_Record::save() ||
|| postSave($event) || Doctrine_Record::save() ||
|| preUpdate($event) || Doctrine_Record::save() when the record state is DIRTY ||
|| postUpdate($event) || Doctrine_Record::save() when the record state is DIRTY ||
|| preInsert($event) || Doctrine_Record::save() when the record state is TDIRTY ||
|| postInsert($event) || Doctrine_Record::save() when the record state is TDIRTY ||
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:
<code type="php">
// here Debugger and Logger both inherit Doctrine_EventListener
$conn->addListener(new Debugger());
$conn->addListener(new Logger());
</code>
++ The Event object
+++ Getting the invoker
You can get the object that invoked the event by calling getInvoker():
<code type="php">
class MyListener extends Doctrine_EventListener
{
public function preExec(Doctrine_Event $event)
{
$event->getInvoker(); // Doctrine_Connection
}
}
</code>
+++ Event codes
Doctrine_Event uses constants as event codes. Above is the list of all available event constants:
The method getInvoker() returns the object that invoked the given event. For example for event Doctrine_Event::CONN_QUERY the invoker is a Doctrine_Connection object. Example:
<code type="php">
class MyRecord extends Doctrine_Record
{
public function preUpdate(Doctrine_Event $event)
{
$event->getInvoker(); // Object(MyRecord)
}
}
</code>
+++ skipOperation()
Doctrine_Event provides many methods for altering the execution of the listened method as well as for altering the behaviour of the listener chain.
For some reason you may want to skip the execution of the listened method. It can be done as follows (note that preExec could be any listener method):
<code type="php">
class MyListener extends Doctrine_EventListener
{
public function preExec(Doctrine_Event $event)
{
// some business logic, then:
$event->skipOperation();
}
}
</code>
+++ skipNextListener()
When using a chain of listeners you might want to skip the execution of the next listener. It can be achieved as follows:
