diff --git a/docs/guide/behaviors.md b/docs/guide/behaviors.md index 2e7bda4f07..6afeddcd71 100644 --- a/docs/guide/behaviors.md +++ b/docs/guide/behaviors.md @@ -2,7 +2,7 @@ Behaviors ========= 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 +code. In particular, a behavior can "inject" its public methods and properties into the component, making them directly accessible via the component itself. A behavior can also respond to events triggered in the component, thus intercepting the normal code execution. Unlike [PHP's traits](http://www.php.net/traits), behaviors can be attached to classes at runtime. @@ -11,10 +11,12 @@ Using behaviors 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 +method. As an example, Yii provides the [[yii\behaviors\TimestampBehavior]] behavior for automatically updating timestamp fields when saving an [[yii\db\ActiveRecord|Active Record]] model: ```php +use yii\behaviors\TimestampBehavior; + class User extends ActiveRecord { // ... @@ -23,7 +25,7 @@ class User extends ActiveRecord { return [ 'timestamp' => [ - 'class' => 'yii\behaviors\AutoTimestamp', + 'class' => TimestampBehavior::className(), 'attributes' => [ ActiveRecord::EVENT_BEFORE_INSERT => ['created_at', 'updated_at'], ActiveRecord::EVENT_BEFORE_UPDATE => 'updated_at', @@ -34,9 +36,38 @@ class User extends ActiveRecord } ``` -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. +In the above, the name `timestamp` can be used to reference the behavior through the component. For example, `$user->timestamp` +gives the attached timestamp behavior instance. The corresponding array is the configuration used to create the +[[yii\behaviors\TimestampBehavior|TimestampBehavior]] object. + +Besides responding to the insertion and update events of ActiveRecord, `TimestampBehavior` also provides a method `touch()` +that can assign the current timestamp to a specified attribute. As aforementioned, you can access this method directly +through the component, like the following: + +```php +$user->touch('login_time'); +``` + +If you do not need to access a behavior object, or the behavior does not need customization, you can also +use the following simplified format when specifying the behavior, + +```php +use yii\behaviors\TimestampBehavior; + +class User extends ActiveRecord +{ + // ... + + public function behaviors() + { + return [ + TimestampBehavior::className(), + // or the following if you want to access the behavior object + // 'timestamp' => TimestampBehavior::className(), + ]; + } +} +``` Creating your own behaviors @@ -54,7 +85,7 @@ class MyBehavior extends Behavior } ``` -To make it customizable, like [[yii\behaviors\AutoTimestamp]], add public properties: +To make it customizable, like [[yii\behaviors\TimestampBehavior]], add public properties: ```php namespace app\components; diff --git a/framework/CHANGELOG.md b/framework/CHANGELOG.md index 9bbdab2203..5d5d940fb8 100644 --- a/framework/CHANGELOG.md +++ b/framework/CHANGELOG.md @@ -152,7 +152,6 @@ Yii Framework 2 Change Log - Removed `yii\web\Request::getPost()`, `getPut()`, `getDelete()`, `getPatch()` in favor of `getBodyParam()` (cebe) - Renamed `yii\web\Request::get()` to `getQueryParams()` and `getRestParams()` to `getBodyParams()` (cebe) - Added `yii\web\Request::get($name = null, $defaultValue = null)` and `yii\web\Request::post($name = null, $defaultValue = null)` (samdark) -- Chg #2057: AutoTimestamp attributes defaults changed from `create_time` and `update_time` to `created_at` and `updated_at` (creocoder) - Chg #2059: Implemented git-flavored file excluding/filtering for `FileHelper` (nineinchnick) - Chg #2063: Removed `yii\web\Request::acceptTypes` and renamed `yii\web\Request::acceptedContentTypes` to `acceptableContentTypes` (qiangxue) - Chg #2157: The '*' category pattern will match all categories that do not match any other patterns listed in `I18N::translations` (qiangxue, Ragazzo) diff --git a/tests/unit/framework/behaviors/TimestampBehaviorTest.php b/tests/unit/framework/behaviors/TimestampBehaviorTest.php index 75ff0b28c2..8a46215704 100644 --- a/tests/unit/framework/behaviors/TimestampBehaviorTest.php +++ b/tests/unit/framework/behaviors/TimestampBehaviorTest.php @@ -10,7 +10,7 @@ use yii\behaviors\TimestampBehavior; /** * Unit test for [[\yii\behaviors\TimestampBehavior]]. - * @see AutoTimestamp + * @see TimestampBehavior * * @group behaviors */ @@ -88,7 +88,7 @@ class TimestampBehaviorTest extends TestCase } /** - * Test Active Record class with [[AutoTimestamp]] behavior attached. + * Test Active Record class with [[TimestampBehavior]] behavior attached. * * @property integer $id * @property integer $created_at