events.md 3 KB
Newer Older
1 2 3
Events
======

Carsten Brandt committed
4
TBD, see also [Component.md](../api/base/Component.md).
5

6 7 8 9 10 11
[[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:
12 13 14

```php
$component->on($eventName, $handler);
15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41
```

[[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.
});
```

42
As shown in the anonymous function example, the event handling function must be defined so that it takes one argument.
43
This will be an [[yii\base\Event]] object.
44 45 46 47 48 49 50 51 52 53 54 55 56 57


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
58 59 60
// $component->off($eventName, $handler);
```

61 62 63 64
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
----------------
65

66
You can make your event handlers easier to work with and more powerful by passing additional values as parameters. 
67 68 69 70 71

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

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

74 75 76 77 78 79
[[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:
80 81 82

```php
Yii::$app->on($eventName, $handler);
83 84 85 86 87 88
```

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

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

92 93 94 95
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:
96 97 98 99 100 101 102 103

```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.