To declare an event in your CComponent child class, you should add a method with a name starting with on. For example, if you add the onRegister method, you will get a corresponding event declared.

Typically, events are used like this:

Let's look at how we can attach an event handler to an event. To achieve it, we can use the CComponent::attachEventHandler method. It accepts the following two parameters:

In PHP, we have several ways to define a callback as follows:

As we now know how to define and use handlers, let's review some real life examples as follows:

Now, let's look at another example. In Yii, you can translate strings to different languages using Yii::t. As we all love perfect projects, all language translations should be up to date.

If they are not, we would like to receive an e-mail about it.

Events come in handy again here. In particular, the CMessageSource::onMissingTranslation event that is called when the translation for a string passed to Yii::t is missing.

This time we will use the application's configuration file protected/config/main.php to attach an event handler as follows:

…
'components' => array(
    …
    // messages component class is CPhpMessageSource by default
    'messages' => array(
        // using static class method as event handler
        'onMissingTranslation' => array('MyEventHandler', 'handleMissingTranslation'),
    ),
    …
)
…

Now, we should implement our handler. Create protected/components/MyEventHandler.php as follows:

class MyEventHandler
{
    static function handleMissingTranslation($event)
    {
        // event class for this event is CMissingTranslationEvent    
        // so we can get some info about the message
        $text = implode("\n", array(
           'Language: '.$event->language,
           'Category:'.$event->category,
           'Message:'.$event->message         
        ));
        // sending email
        mail('[email protected]', 'Missing translation', $text);
    }
}

Let's look at another example. Let's assume we have a blog application and we need to send an e-mail when there is a new comment (Comment) to the blog post (Post).

Comment is a standard AR model generated with Gii. Post is the same Gii-generated model except for some customized methods. We will need a custom event, NewCommentEvent, to store both Post and Comment models and a handler class, Notifier, that will do the work.

It is not always necessary to attach an event handler. Let's look at how we can handle an event that is already declared inside an existing component by overriding a method of the base class. For example, we have a form model UserForm used to collect some information about our application user and we need to get the complete name from the first and the last name entered by the user.

Fortunately, in CModel, which is the base class for all Yii models including form models, the CModel::afterValidate method is defined. This method is called after a successful form validation. Let's use it in our protected/models/UserForm.php model:

class UserForm extends CFormModel
{
    public $firstName;
    public $lastName;
    public $fullName;

    public function rules()
    {
        return array(
            // First name and last name are required
            array('firstName, lastName', 'required'),
        );
    }

    function afterValidate()
    {
        // If this method was called then
        // the model is already filled
        // with data and data is valid
        // so we can use it safely:
        $this->fullName = $this->firstName.' '.$this->lastName;

        // It's important to call parent class method
        // so all other event handlers are called
        return parent::afterValidate();
    }
}

We need to call the parent method inside of the afterValidate function because parent implementation calls onAfterValidate that actually raises events:

protected function afterValidate()
{
   $this->onAfterValidate(new CEvent($this));
}

The approach described here can be used to customize your Active Record models and implement your own model behaviors.