Skip to content

Latest commit

 

History

History
103 lines (69 loc) · 3.01 KB

events.md

File metadata and controls

103 lines (69 loc) · 3.01 KB
Raw

Events

TBD, see also Component.md.

[[ADD INTRODUCTION]]

Creating Event Handlers

In Yii 1, events were defined using the onEventName method syntax, such as onBeforeSave. This is no longer necessary in Yii 2, as event handling is now assigned using the on method. The method's first argument is the name of the event to watch for; the second is the handling method to be called when that event occurs:

$component->on($eventName, $handler);

[[LINK TO LIST OF EVENTS]]

The handler must be a valid PHP callback. This could be represented as:

  • The name of a global function
  • An array consisting of a model name and method name
  • An array consisting of an object and a method name
  • An anonymous function
// Global function:
$component->on($eventName, 'functionName');

// Model and method names:
$component->on($eventName, ['Modelname', 'functionName']);

// Object and method name:
$component->on($eventName, [$obj, 'functionName']);

// Anonymous function:
$component->on($eventName, function($event) {
	// Use $event.
});

As shown in the anonymous function example, the event handling function must be defined so that it takes one argument. This will be an [[\yii\base\Event]] object.

Removing Event Handlers

The correspondoing off method removes an event handler:

// $component->off($eventName);

Yii supports the ability to associate multiple handlers with the same event. When using off as in the above, every handler is removed. To remove only a specific handler, provide that as the second argument to off:

// $component->off($eventName, $handler);

The $handler should be presented in the off method in the same way as was presented in on in order to remove it.

Event Parameters

You can make your event handlers easier to work with and more powerful by passing additional values as parameters.

$component->on($eventName, $handler, $params);

The passed parameters will be available in the event handler through $event->data, which will be an array.

[[NEED TO CONFIRM THE ABOVE]]

Global Events

Thanks to the change in Yii 2 as to how event handlers are created, you can now use "global" events. To create a global event, simply attach handlers to an event on the application instance:

Yii::$app->on($eventName, $handler);

You can use the trigger method to trigger these events manually:

// this will trigger the event and cause $handler to be invoked:
Yii::$app->trigger($eventName);

Class Events

You can also attach event handlers to all instances of a class instead of individual instances. To do so, use the static Event::on method:

Event::on(ActiveRecord::className(), ActiveRecord::EVENT_AFTER_INSERT, function ($event) {
	Yii::trace(get_class($event->sender) . ' is inserted.');
});

The code above defines a handler that will be triggered for every Active Record object's EVENT_AFTER_INSERT event.