Event listeners has been available since EZPDO v1.0.1.

It is often useful for your application to react to certain events that occur inside EZPDO. For example, a Web application may want to validate data before committing any changes, or act upon (for example, send email or instant message to notify or alert) when a new account has been created or deleted.

The following events are supported in EZPDO.

A listener is a class that contains callback methods to process EZPDO events listed above.1) For example, if a listener class is intesrested in the onUpdate event, it needs to implement a callback method with the same name, onUpdate(). EZPDO supports two types of listeners: global and local.

A global listener listens to events for objects of all classes persisted by EZPDO. It needs to be registered to the EZPDO manager (epManager) for it to be functional, and all its callback methods will be passed with the object as the parameter.

Here is an exmaple of a listener that only listens to onLoad and onUpdate event.

 class MyListener {
    
    /**
     * process event onLoad()
     */ 
    function onLoad(epObject $o, $params = null) {
        // processing onLoad event
        // ......
    }
    
    /**
     * process event onUpdate(epObject $o, $params = null)
     */ 
    function onUpdate(epObject $o) {
        // processing onUpdate event
        // ......
    }
    
}

Before the listener is called by the EZPDO manager, you need to register it with the manager.

// get the manager
$m = epManager::instance();
 
// instantiate listener 
$l = new MyListener;
 
// register listener 
$m->register($l);
 

Or you simply pass the listener class (in which case EZPDO will instantiate the listener)

// register listener class
$m->register('MyListener');

During runtime, if you want to stop listener from “listening” events, simply do

// unregister listener instance
$m->unregister($l);

Or if you want to remove all listener instances of a class

// register listener by class
$m->unregister('MyListener');

A local listener only listens to events related to a particular class that’s persisted by EZPDO and is completely implemented in the class.

For example, if you have a class to be persisted by EZPDO and you want to turn it into a listener that processes events onLoad and onUpdate, you need to add event callback methods,

class MyClass {
    
    /**
     * @var integer
     * @orm integer  
     */
    public var1;
 
    /**
     * @var string
     * @orm char(128)  
     */
    public var2;
 
    /**
     * process event onLoad()
     */ 
    function onLoad($params = null) {
        // process the onLoad event here
	// ......
    }
 
    /**
     * Callback to process event onUpdate()
     */ 
    function onUpdate($params = null) {
        // process the onUpdate event here
	// ......
    }
 
}

Similar to global listeners, before the local listener are enabled to listen to events, you need to register it with the manager.

$m = epManager::instance();
$m->register('MyClass');

If you want to stop listener from “listening” events, simply unregister it

$m->unregister('MyClass');

Two differences between a local listener and a global listener:

1. Callback functions of local listeners are not passed with the object involved as argument.
2. Local listener can only be (un)registered on a class level. That is, you cannot register an instance of a persistent class.

According to what is involved in an event, there are two categories of events (and thus callbacks): object-level and class-level. We say an event (or a callback) is object-level if it involves only a particular persistent object (for example onLoad and onUpdate) and class-level if it involves a persistent class (for example onDeleteAll).

For a global listener, an object-level event passes the involved objects as the first argument along with an array of other parameters (if any) to the event callback method in the listener, while a class-level event passes the class name along with an array of other parameters (if any) to the callback method.

For a local listener, none of the involved object or class is passed to the listener. An event, either object-level or class-level, only passes an array of auxilliary parameters (if any) to the listener.

All callbacks should be public. For a global listener, a callback can be either static or non-static. For a local listener, however, a class-level callback must be static for it to be accessible to receive events.

The following table summarizes callback categories.

Please note that the Static? column is only applicable to class-level listeners.

The event listener API on epManager. This is part of the runtime API.

• boolean register($l)
  • Description: register an event listener with the manager
  • Parameter: string|object $l the name of the listener class or a (global) listener instance
  • Return: boolean

• integer unregister($l)
  • Description: unregister (remove) an event listener instance of a listener class from the manager
  • Parameter: string|object $l the name of the listener class or a (global) listener instance
  • Return: false|integer (the number of global instances or local listener classes removed)