mirror of
https://github.com/yiisoft/yii2.git
synced 2025-11-12 11:40:19 +08:00
104 lines
3.0 KiB
Markdown
104 lines
3.0 KiB
Markdown
Events
|
|
======
|
|
|
|
TBD, see also [Component.md](../api/base/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:
|
|
|
|
```php
|
|
$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
|
|
|
|
```php
|
|
// 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:
|
|
|
|
```php
|
|
// $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`:
|
|
|
|
```php
|
|
// $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.
|
|
|
|
```php
|
|
$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:
|
|
|
|
```php
|
|
Yii::$app->on($eventName, $handler);
|
|
```
|
|
|
|
You can use the `trigger` method to trigger these events manually:
|
|
|
|
```php
|
|
// 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:
|
|
|
|
```php
|
|
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.
|