Sometimes we would like to monitor when something special occurs in our web application. It could be when a user withdraws certain amount of money from their account or when we save an instance of a model.

This “special occurrence” is called an event. The object in which the event occurs is called the event generator. This could be a model that represents the user’s account.

The object that will listen to and perform a task when the event occurs is called the event handler. For a given event, there could be many event handlers listening to it because each may need to do something different.

So how would an event handler know that a certain event has occurred? There need to be a kind of registration service for the event handlers to register themselves. This registration service is usually provided by the event generator.

In Yii, an event handler is implemented as a callback function. The function takes as its parameter, the event that occurred. The event will be an instance of the CEvent or its derived class. This event carries the information about what has just happened. At the minimum, it contains the information about which object raised the event, which is the event generator. It can contain other information.

As mentioned earlier, there could be many handlers listening to a particular event. The framework will call then in turn in order which they were added to the registration service. If there need arises to prevent other handlers from performing their task because you have appropriately handled the event in a previous handler, you should set the event property handled to true. When the framework detects that the handled property is set to true, it will stop calling the other handlers.

To register an event handler, you call attachEventHandle which every object that extends the CComponent has. It takes as its parameter, the name of the event and the callback for that event.

public void attachEventHandler(string $name, callback $handler)

Below are some examples of how we can specify the callback parameter.

'handleOnClick'                   // handleOnClick() is a global function
array($object,'handleOnClick')    // using $object->handleOnClick()
array('Page','handleOnClick')     // using Page::handleOnClick()

The signature of the callback function must be as follows:

function methodName($event){
 …….
}

where $event is the parameter describing the event.

There are other ways to attach event handlers to an event. Suppose $component is an instance of a CComponent, calling

$component->onClick=$callback;    
// or 
$component->onClick->add($callback);

will attach the callback to the ‘onClick’ event. Behind the scene, Yii adds this callback to the event handler list for the ‘onClick’ event.

Any component’s property that begins with ‘on’ which does not have an associated setter method is considered to be a declaration to attach an event handler.

Because code may be read by other people who are not familiar with some of these shortcuts in Yii, I will recommend that developers use the attachEventHandler when they can.

If for any reason you want to remove an event handler you attached earlier, you can call detachEventHandler. This will remove any previously attached handler for the event.

If you also want to check if an event has an event handler, you can use the hasEventHandler(). It takes as its parameter, the name of the event you want to check.

So how do we signal event handlers that an event has occurred? You notify events listeners interested in the event by calling the raiseEvent(string $name, CEvent $event) method.

The name parameter tells Yii’s event handling system that the event with this name has occurred. Information regarding the event is encapsulated in this parameter. This is the event given to the event handler or callback. When the event is raised, handlers attached to the event will be invoked automatically.

In the next posts, we will discuss patterns/ways you can handle events in Yii.