Events explained

Let's see what exactly are the events in Yii!

What is an event? It is the fact that we want to express that in certain points in our source code something happens!

Let's say that we are inside a function called runForestRun() Instead of simply executing the code of this function we would like in addition to express that forest ran. In other words to say that this event has occured. Why? Because maybe others are interested that this event has occured and they would like to react!

So we want this:

function runForestRun(){ //some point in our code, either function or method
    //... arbitrary code before raising the event
    $myComponent->onForestRan(new CEvent($this));
    //... maybe some code over here after raising the event
}

In the first place the

new CEvent($this)

is just the basic object event of Yii. The CEvent class can of course be extended in case we want to get extra functionality. (like the CModelEvent which is used inside CActiveRecord)

Yeah ok I know, the myComponent does not have a method "onForestRan" yet that's why we should declare it inside the component like this:

public function onForestRan($event){
    $this->raiseEvent('onForestRan', $event);
}

Typically here we simply call raise event but certainly someone could add extra code, usually before calling raiseEvent if he wishes something extra. The standard convention is that an event is defined with the on prefix and after the name of the event with the first letter upper-case.

Cool let's say we executed event and we yelled that forest has ran! But who is going to listen? The computer cannot guess by itself therefore we should tell it who is interested! In other words to define the handlers.

So earlier before raising the event we should have called, maybe inside the initialization method of the component, something like this:

$myComponent->onForestRan = array(new SomeOtherClass, 'eventHandler1');

or that:

$myComponent->onForestRan = function() {};

or in general any callback function is valid in php: http://php.net/manual/en/language.pseudo-types.php

We define one line for each one that has interest that forest ran! In other words we could say that we prepare a list of functions or methods (static or not) that will be executed one by one when the event is raised.

The event handlers must have a signature like this:

function eventHandler1($event) {
}

And now we can grab the sender object by $event->sender ;)

Please note that when a class (a component) yells that an event has happened (that forest ran) then it is more sane that the event handlers (those of interest to the event) are other entities! To define a method inside the same class is technically possible but without much of sense!

So let's do a resume of the events in three steps:

1) Define the event we want as a method inside the class with the prefix on and typically inside it we call the raiseEvent.

2) Define all the callback functions (the handlers) which they will be called when the event is going to be raised and we are done with the preperation of the event.

3) Insert the statement $myComponent->onForestRan(new CEvent($this)); in every point of the source code that is necessary in order for the event to be raised at runtime.

Please do not hesitate to ask me if not everything is understood :)

References: http://www.yiiframework.com/doc/guide/1.1/en/basics.component#component-event

http://www.yiiframework.com/wiki/44/behaviors-events

http://www.yiiframework.com/wiki/255/using-events-with-caction-classes