behaviors.md 2.91 KB
Newer Older
1 2 3
Behaviors
=========

4 5
A behavior (also knows as *mixin*) can be used to enhance the functionality of an existing component without modifying the component's
code. In particular, a behavior can "inject" its own methods and properties into the component, making them directly accessible
kate-kate committed
6
via the component itself. A behavior can also respond to  events triggered in the component, thus intercepting the normal
7
code execution. Unlike [PHP's traits](http://www.php.net/traits), behaviors can be attached to classes at runtime.
8 9 10 11

Using behaviors
---------------

12 13 14 15
A behavior can be attached to any class that extends from [[yii\base\Component]]. In order to attach a behavior to a class,
the component class must implement the `behaviors`
method. As an example, Yii provides the [[yii\behaviors\AutoTimestamp|AutoTimestamp]] behavior for automatically updating timestamp
fields when saving an [[yii\db\ActiveRecord|Active Record]] model:
16 17 18 19 20 21 22 23 24 25 26 27

```php
class User extends ActiveRecord
{
	// ...

	public function behaviors()
	{
		return [
			'timestamp' => [
				'class' => 'yii\behaviors\AutoTimestamp',
				'attributes' => [
Alexander Kochetov committed
28 29
					ActiveRecord::EVENT_BEFORE_INSERT => ['created_at', 'updated_at'],
					ActiveRecord::EVENT_BEFORE_UPDATE => 'updated_at',
30 31 32 33 34 35 36
				],
			],
		];
	}
}
```

37 38 39 40
In the above, the `class` value is a string representing the fully qualified behavior class name.
All of the other key-value pairs represent corresponding public properties of the [[yii\behaviors\AutoTimestamp|AutoTimestamp]]
class, thereby customizing how the behavior functions.

41 42 43 44

Creating your own behaviors
---------------------------

45
To create your own behavior, you must define a class that extends [[yii\base\Behavior]].
46 47

```php
48 49 50 51 52
namespace app\components;

use yii\base\Behavior;

class MyBehavior extends Behavior
53 54 55 56
{
}
```

57
To make it customizable, like [[yii\behaviors\AutoTimestamp]], add public properties:
58 59

```php
60 61 62 63 64
namespace app\components;

use yii\base\Behavior;

class MyBehavior extends Behavior
65 66 67 68 69 70 71 72
{
	public $attr;
}
```

Now, when the behavior is used, you can set the attribute to which you'd want the behavior to be applied:

```php
73 74 75 76
namespace app\models;

use yii\db\ActiveRecord;

77 78 79 80 81 82 83 84
class User extends ActiveRecord
{
	// ...

	public function behaviors()
	{
		return [
			'mybehavior' => [
85
				'class' => 'app\components\MyBehavior',
86 87 88 89 90 91 92
				'attr' => 'member_type'
			],
		];
	}
}
```

93 94
Behaviors are normally written to take action when certain events occur. Below we're implementing `events` method
to assign event handlers:
95 96

```php
97 98 99 100 101 102
namespace app\components;

use yii\base\Behavior;
use yii\db\ActiveRecord;

class MyBehavior extends Behavior
103 104
{
	public $attr;
105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120

	public function events()
	{
		return [
			ActiveRecord::EVENT_BEFORE_INSERT => 'beforeInsert',
			ActiveRecord::EVENT_BEFORE_UPDATE => 'beforeUpdate',
		];
	}

	public function beforeInsert() {
		$model = $this->owner;
		// Use $model->$attr
	}

	public function beforeUpdate() {
		$model = $this->owner;
121 122 123
		// Use $model->$attr
	}
}
Alexander Kochetov committed
124
```