|
|
|
@ -9,50 +9,90 @@ can respond to the [events](concept-events.md) triggered by the component, which
|
|
|
|
|
code execution of the component. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using Behaviors <a name="using-behaviors"></a> |
|
|
|
|
--------------- |
|
|
|
|
Defining Behaviors <a name="defining-behaviors"></a> |
|
|
|
|
------------------ |
|
|
|
|
|
|
|
|
|
To use a behavior, you first need to attach it to a [[yii\base\Component|component]]. We will describe how to |
|
|
|
|
attach a behavior in the next subsection. |
|
|
|
|
To define a behavior, create a class by extending from [[yii\base\Behavior]] or its child class. For example, |
|
|
|
|
|
|
|
|
|
Once a behavior is attached to a component, its usage is straightforward. |
|
|
|
|
```php |
|
|
|
|
namespace app\components; |
|
|
|
|
|
|
|
|
|
You can access a *public* member variable or a [property](concept-properties.md) defined by a getter and/or a setter |
|
|
|
|
of the behavior through the component it is attached to, like the following, |
|
|
|
|
use yii\base\Model; |
|
|
|
|
use yii\base\Behavior; |
|
|
|
|
|
|
|
|
|
```php |
|
|
|
|
// "prop1" is a property defined in the behavior class |
|
|
|
|
echo $component->prop1; |
|
|
|
|
$component->prop1 = $value; |
|
|
|
|
``` |
|
|
|
|
class MyBehavior extends Behavior |
|
|
|
|
{ |
|
|
|
|
public $prop1; |
|
|
|
|
|
|
|
|
|
You can also call a *public* method of the behavior similarly, |
|
|
|
|
private $_prop2; |
|
|
|
|
|
|
|
|
|
```php |
|
|
|
|
// bar() is a public method defined in the behavior class |
|
|
|
|
$component->bar(); |
|
|
|
|
public function getProp2() |
|
|
|
|
{ |
|
|
|
|
return $this->_prop2; |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
public function setProp2($value) |
|
|
|
|
{ |
|
|
|
|
$this->_prop2 = $value; |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
public function foo() |
|
|
|
|
{ |
|
|
|
|
// ... |
|
|
|
|
} |
|
|
|
|
} |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
As you can see, although `$component` does not define `prop1` and `bar()`, they can be used as if they are part |
|
|
|
|
of the component definition. |
|
|
|
|
The above code defines the behavior class `app\components\MyBehavior` which will provide two properties |
|
|
|
|
`prop1` and `prop2`, and one method `foo()` to the component it is attached to. Note that property `prop2` |
|
|
|
|
is defined via the getter `getProp2()` and the setter `setProp2()`. This is so because [[yii\base\Object]] |
|
|
|
|
is an ancestor class of [[yii\base\Behavior]], which supports defining [properties](concept-properties.md) by getters/setters. |
|
|
|
|
|
|
|
|
|
If two behaviors define the same property or method and they are both attached to the same component, |
|
|
|
|
the behavior that is attached to the component first will take precedence when the property or method is being accessed. |
|
|
|
|
Within a behavior, you can access the component that the behavior is attached to through the [[yii\base\Behavior::owner]] property. |
|
|
|
|
|
|
|
|
|
A behavior may be associated with a name when it is attached to a component. If this is the case, you may |
|
|
|
|
access the behavior object using the name, like the following, |
|
|
|
|
If a behavior needs to respond to the events triggered by the component it is attached to, it should override the |
|
|
|
|
[[yii\base\Behavior::events()]] method. For example, |
|
|
|
|
|
|
|
|
|
```php |
|
|
|
|
$behavior = $component->getBehavior('myBehavior'); |
|
|
|
|
namespace app\components; |
|
|
|
|
|
|
|
|
|
use yii\db\ActiveRecord; |
|
|
|
|
use yii\base\Behavior; |
|
|
|
|
|
|
|
|
|
class MyBehavior extends Behavior |
|
|
|
|
{ |
|
|
|
|
// ... |
|
|
|
|
|
|
|
|
|
public function events() |
|
|
|
|
{ |
|
|
|
|
return [ |
|
|
|
|
ActiveRecord::EVENT_BEFORE_VALIDATE => 'beforeValidate', |
|
|
|
|
]; |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
public function beforeValidate($event) |
|
|
|
|
{ |
|
|
|
|
// ... |
|
|
|
|
} |
|
|
|
|
} |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
You may also get all behaviors attached to a component: |
|
|
|
|
The [[yii\base\Behavior::events()|events()]] method should return a list of events and their corresponding handlers. |
|
|
|
|
The above example declares that the [[yii\db\ActiveRecord::EVENT_BEFORE_VALIDATE|EVENT_BEFORE_VALIDATE]] event and |
|
|
|
|
its handler `beforeValidate()`. When specifying an event handler, you may use one of the following formats: |
|
|
|
|
|
|
|
|
|
* a string that refers to the name of a method of the behavior class, like the example above; |
|
|
|
|
* an array of an object or class name, and a method name, e.g., `[$object, 'methodName']`; |
|
|
|
|
* an anonymous function. |
|
|
|
|
|
|
|
|
|
The signature of an event handler should be as follows, where `$event` refers to the event parameter. Please refer |
|
|
|
|
to the [Events](concept-events.md) section for more details about events. |
|
|
|
|
|
|
|
|
|
```php |
|
|
|
|
$behaviors = $component->getBehaviors(); |
|
|
|
|
function ($event) { |
|
|
|
|
} |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Attaching Behaviors <a name="attaching-behaviors"></a> |
|
|
|
|
------------------- |
|
|
|
|
|
|
|
|
@ -150,108 +190,69 @@ please refer to the [Configurations](concept-configurations.md#configuration-for
|
|
|
|
|
] |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
Using Behaviors <a name="using-behaviors"></a> |
|
|
|
|
--------------- |
|
|
|
|
|
|
|
|
|
Detaching Behaviors <a name="detaching-behaviors"></a> |
|
|
|
|
------------------- |
|
|
|
|
To use a behavior, you first need to attach it to a [[yii\base\Component|component]]. We will describe how to |
|
|
|
|
attach a behavior in the next subsection. |
|
|
|
|
|
|
|
|
|
To detach a behavior, you can call [[yii\base\Component::detachBehavior()]] with the name associated with the behavior: |
|
|
|
|
Once a behavior is attached to a component, its usage is straightforward. |
|
|
|
|
|
|
|
|
|
You can access a *public* member variable or a [property](concept-properties.md) defined by a getter and/or a setter |
|
|
|
|
of the behavior through the component it is attached to, like the following, |
|
|
|
|
|
|
|
|
|
```php |
|
|
|
|
$component->detachBehavior('myBehavior1'); |
|
|
|
|
// "prop1" is a property defined in the behavior class |
|
|
|
|
echo $component->prop1; |
|
|
|
|
$component->prop1 = $value; |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
You may also detach *all* behaviors: |
|
|
|
|
You can also call a *public* method of the behavior similarly, |
|
|
|
|
|
|
|
|
|
```php |
|
|
|
|
$component->detachBehaviors(); |
|
|
|
|
// bar() is a public method defined in the behavior class |
|
|
|
|
$component->bar(); |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
As you can see, although `$component` does not define `prop1` and `bar()`, they can be used as if they are part |
|
|
|
|
of the component definition. |
|
|
|
|
|
|
|
|
|
Defining Behaviors <a name="defining-behaviors"></a> |
|
|
|
|
------------------ |
|
|
|
|
If two behaviors define the same property or method and they are both attached to the same component, |
|
|
|
|
the behavior that is attached to the component first will take precedence when the property or method is being accessed. |
|
|
|
|
|
|
|
|
|
To define a behavior, create a class by extending from [[yii\base\Behavior]] or its child class. For example, |
|
|
|
|
A behavior may be associated with a name when it is attached to a component. If this is the case, you may |
|
|
|
|
access the behavior object using the name, like the following, |
|
|
|
|
|
|
|
|
|
```php |
|
|
|
|
namespace app\components; |
|
|
|
|
|
|
|
|
|
use yii\base\Model; |
|
|
|
|
use yii\base\Behavior; |
|
|
|
|
|
|
|
|
|
class MyBehavior extends Behavior |
|
|
|
|
{ |
|
|
|
|
public $prop1; |
|
|
|
|
|
|
|
|
|
private $_prop2; |
|
|
|
|
|
|
|
|
|
public function getProp2() |
|
|
|
|
{ |
|
|
|
|
return $this->_prop2; |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
public function setProp2($value) |
|
|
|
|
{ |
|
|
|
|
$this->_prop2 = $value; |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
public function foo() |
|
|
|
|
{ |
|
|
|
|
// ... |
|
|
|
|
} |
|
|
|
|
} |
|
|
|
|
$behavior = $component->getBehavior('myBehavior'); |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
The above code defines the behavior class `app\components\MyBehavior` which will provide two properties |
|
|
|
|
`prop1` and `prop2`, and one method `foo()` to the component it is attached to. Note that property `prop2` |
|
|
|
|
is defined via the getter `getProp2()` and the setter `setProp2()`. This is so because [[yii\base\Object]] |
|
|
|
|
is an ancestor class of [[yii\base\Behavior]], which supports defining [properties](concept-properties.md) by getters/setters. |
|
|
|
|
|
|
|
|
|
Within a behavior, you can access the component that the behavior is attached to through the [[yii\base\Behavior::owner]] property. |
|
|
|
|
|
|
|
|
|
If a behavior needs to respond to the events triggered by the component it is attached to, it should override the |
|
|
|
|
[[yii\base\Behavior::events()]] method. For example, |
|
|
|
|
You may also get all behaviors attached to a component: |
|
|
|
|
|
|
|
|
|
```php |
|
|
|
|
namespace app\components; |
|
|
|
|
$behaviors = $component->getBehaviors(); |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
use yii\db\ActiveRecord; |
|
|
|
|
use yii\base\Behavior; |
|
|
|
|
|
|
|
|
|
class MyBehavior extends Behavior |
|
|
|
|
{ |
|
|
|
|
// ... |
|
|
|
|
|
|
|
|
|
public function events() |
|
|
|
|
{ |
|
|
|
|
return [ |
|
|
|
|
ActiveRecord::EVENT_BEFORE_VALIDATE => 'beforeValidate', |
|
|
|
|
]; |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
public function beforeValidate($event) |
|
|
|
|
{ |
|
|
|
|
// ... |
|
|
|
|
} |
|
|
|
|
} |
|
|
|
|
``` |
|
|
|
|
Detaching Behaviors <a name="detaching-behaviors"></a> |
|
|
|
|
------------------- |
|
|
|
|
|
|
|
|
|
The [[yii\base\Behavior::events()|events()]] method should return a list of events and their corresponding handlers. |
|
|
|
|
The above example declares that the [[yii\db\ActiveRecord::EVENT_BEFORE_VALIDATE|EVENT_BEFORE_VALIDATE]] event and |
|
|
|
|
its handler `beforeValidate()`. When specifying an event handler, you may use one of the following formats: |
|
|
|
|
To detach a behavior, you can call [[yii\base\Component::detachBehavior()]] with the name associated with the behavior: |
|
|
|
|
|
|
|
|
|
* a string that refers to the name of a method of the behavior class, like the example above; |
|
|
|
|
* an array of an object or class name, and a method name, e.g., `[$object, 'methodName']`; |
|
|
|
|
* an anonymous function. |
|
|
|
|
```php |
|
|
|
|
$component->detachBehavior('myBehavior1'); |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
The signature of an event handler should be as follows, where `$event` refers to the event parameter. Please refer |
|
|
|
|
to the [Events](concept-events.md) section for more details about events. |
|
|
|
|
You may also detach *all* behaviors: |
|
|
|
|
|
|
|
|
|
```php |
|
|
|
|
function ($event) { |
|
|
|
|
} |
|
|
|
|
$component->detachBehaviors(); |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using `TimestampBehavior` <a name="using-timestamp-behavior"></a> |
|
|
|
|
------------------------- |
|
|
|
|
|
|
|
|
|