model.md 15.3 KB
Newer Older
Alexander Makarov committed
1 2 3
Model
=====

Alexander Makarov committed
4 5
In keeping with the MVC approach, a model in Yii is intended for storing or temporarily representing application data.
Yii models have the following basic features:
Alexander Makarov committed
6

Larry Ullman committed
7 8 9 10
- Attribute declaration: a model defines what is considered an attribute.
- Attribute labels: each attribute may be associated with a label for display purpose.
- Massive attribute assignment: the ability to populate multiple model attributes in one step.
- Scenario-based data validation.
Alexander Makarov committed
11

12
Models in Yii extend from the [[yii\base\Model]] class. Models are typically used to both hold data and define
Alexander Makarov committed
13 14 15 16 17
the validation rules for that data (aka, the business logic). The business logic greatly simplifies the generation
of models from complex web forms by providing validation and error reporting.

The Model class is also the base class for more advanced models with additional functionality, such
as [Active Record](active-record.md).
Alexander Makarov committed
18 19 20 21

Attributes
----------

22 23 24
The actual data represented by a model is stored in the model's *attributes*. Model attributes can
be accessed like the member variables of any object. For example, a `Post` model
may contain a `title` attribute and a `content` attribute, accessible as follows:
Alexander Makarov committed
25 26

```php
27
$post = new Post();
Alexander Makarov committed
28
$post->title = 'Hello, world';
Alexander Makarov committed
29
$post->content = 'Something interesting is happening.';
Alexander Makarov committed
30 31 32 33
echo $post->title;
echo $post->content;
```

34
Since [[yii\base\Model|Model]] implements the [ArrayAccess](http://php.net/manual/en/class.arrayaccess.php) interface,
35
you can also access the attributes as if they were array elements:
Alexander Makarov committed
36 37

```php
38
$post = new Post();
Alexander Makarov committed
39 40 41 42 43 44
$post['title'] = 'Hello, world';
$post['content'] = 'Something interesting is happening';
echo $post['title'];
echo $post['content'];
```

45
By default, [[yii\base\Model|Model]] requires that attributes be declared as *public* and *non-static*
Qiang Xue committed
46 47
class member variables. In the following example, the `LoginForm` model class declares two attributes:
`username` and `password`.
Alexander Makarov committed
48 49 50 51 52

```php
// LoginForm has two attributes: username and password
class LoginForm extends \yii\base\Model
{
53 54
    public $username;
    public $password;
Alexander Makarov committed
55 56 57
}
```

58 59
Derived model classes may declare attributes in different ways, by overriding the [[yii\base\Model::attributes()|attributes()]]
method. For example, [[yii\db\ActiveRecord]] defines attributes using the column names of the database table
Qiang Xue committed
60
that is associated with the class.
Alexander Makarov committed
61 62


Qiang Xue committed
63
Attribute Labels
Carsten Brandt committed
64
----------------
Alexander Makarov committed
65 66

Attribute labels are mainly used for display purpose. For example, given an attribute `firstName`, we can declare
67
a label `First Name` that is more user-friendly when displayed to end users in places such as form labels and
68
error messages. Given an attribute name, you can obtain its label by calling [[yii\base\Model::getAttributeLabel()]].
Alexander Makarov committed
69

70
To declare attribute labels, override the [[yii\base\Model::attributeLabels()]] method. The overridden method returns
Alexander Makarov committed
71
a mapping of attribute names to attribute labels, as shown in the example below. If an attribute is not found
72 73
in this mapping, its label will be generated using the [[yii\base\Model::generateAttributeLabel()]] method.
In many cases, [[yii\base\Model::generateAttributeLabel()]] will generate reasonable labels (e.g. `username` to `Username`,
Alexander Makarov committed
74
`orderNumber` to `Order Number`).
Alexander Makarov committed
75 76 77 78 79

```php
// LoginForm has two attributes: username and password
class LoginForm extends \yii\base\Model
{
80 81 82 83 84 85 86 87 88 89
    public $username;
    public $password;

    public function attributeLabels()
    {
        return [
            'username' => 'Your name',
            'password' => 'Your password',
        ];
    }
Alexander Makarov committed
90 91 92 93 94 95
}
```

Scenarios
---------

96
A model may be used in different *scenarios*. For example, a `User` model may be used to collect user login inputs,
Alexander Makarov committed
97 98
but it may also be used for user registration purposes. In the one scenario, every piece of data is required;
in the other, only the username and password would be.
99 100 101 102

To easily implement the business logic for different scenarios, each model has a property named `scenario`
that stores the name of the scenario that the model is currently being used in. As will be explained in the next
few sections, the concept of scenarios is mainly used for data validation and massive attribute assignment.
Alexander Makarov committed
103 104 105

Associated with each scenario is a list of attributes that are *active* in that particular scenario. For example,
in the `login` scenario, only the `username` and `password` attributes are active; while in the `register` scenario,
106
additional attributes such as `email` are *active*. When an attribute is *active* this means that it is subject to validation.
Alexander Makarov committed
107

108 109
Possible scenarios should be listed in the `scenarios()` method. This method returns an array whose keys are the scenario
names and whose values are lists of attributes that should be active in that scenario:
Alexander Makarov committed
110 111 112 113

```php
class User extends \yii\db\ActiveRecord
{
114 115 116 117 118 119 120
    public function scenarios()
    {
        return [
            'login' => ['username', 'password'],
            'register' => ['username', 'email', 'password'],
        ];
    }
Alexander Makarov committed
121 122 123
}
```

Alexander Makarov committed
124 125 126
If `scenarios` method is not defined, default scenario is applied. That means attributes with validation rules are
considered *active*.

127 128 129 130
If you want to keep the default scenario available besides your own scenarios, use inheritance to include it:
```php
class User extends \yii\db\ActiveRecord
{
131 132 133 134 135 136 137
    public function scenarios()
    {
        $scenarios = parent::scenarios();
        $scenarios['login'] = ['username', 'password'];
        $scenarios['register'] = ['username', 'email', 'password'];
        return $scenarios;
    }
138 139 140 141
}
```


142 143
Sometimes, we want to mark an attribute as not safe for massive assignment (but we still want the attribute to be validated).
We may do so by prefixing an exclamation character to the attribute name when declaring it in `scenarios()`. For example:
Alexander Makarov committed
144 145

```php
Alexander Makarov committed
146
['username', 'password', '!secret']
Alexander Makarov committed
147 148
```

149 150 151
In this example `username`, `password` and `secret` are *active* attributes but only `username` and `password` are
considered safe for massive assignment.

152
Identifying the active model scenario can be done using one of the following approaches:
153 154 155 156

```php
class EmployeeController extends \yii\web\Controller
{
157 158 159 160 161 162 163 164 165 166 167 168 169 170 171
    public function actionCreate($id = null)
    {
        // first way
        $employee = new Employee(['scenario' => 'managementPanel']);

        // second way
        $employee = new Employee();
        $employee->scenario = 'managementPanel';

        // third way
        $employee = Employee::find()->where('id = :id', [':id' => $id])->one();
        if ($employee !== null) {
            $employee->scenario = 'managementPanel';
        }
    }
172 173 174
}
```

175
The example above presumes that the model is based upon [Active Record](active-record.md). For basic form models,
Alexander Makarov committed
176 177 178
scenarios are rarely needed, as the basic form model is normally tied directly to a single form and, as noted above,
the default implementation of the `scenarios()` returns every property with active validation rule making it always
available for mass assignment and validation.
179

180

Alexander Makarov committed
181 182 183 184 185 186 187 188 189
Validation
----------

When a model is used to collect user input data via its attributes, it usually needs to validate the affected attributes
to make sure they satisfy certain requirements, such as an attribute cannot be empty, an attribute must contain letters
only, etc. If errors are found in validation, they may be presented to the user to help him fix the errors.
The following example shows how the validation is performed:

```php
190
$model = new LoginForm();
Alexander Makarov committed
191 192 193
$model->username = $_POST['username'];
$model->password = $_POST['password'];
if ($model->validate()) {
194
    // ... login the user ...
Alexander Makarov committed
195
} else {
196 197
    $errors = $model->getErrors();
    // ... display the errors to the end user ...
Alexander Makarov committed
198 199 200 201 202
}
```

The possible validation rules for a model should be listed in its `rules()` method. Each validation rule applies to one
or several attributes and is effective in one or several scenarios. A rule can be specified using a validator object - an
203
instance of a [[yii\validators\Validator]] child class, or an array with the following format:
Alexander Makarov committed
204 205

```php
Alexander Makarov committed
206
[
207 208 209 210 211 212 213 214 215 216
    ['attribute1', 'attribute2', ...],
    'validator class or alias',
    // specifies in which scenario(s) this rule is active.
    // if not given, it means it is active in all scenarios
    'on' => ['scenario1', 'scenario2', ...],
    // the following name-value pairs will be used
    // to initialize the validator properties
    'property1' => 'value1',
    'property2' => 'value2',
    // ...
Alexander Makarov committed
217
]
Alexander Makarov committed
218 219 220 221
```

When `validate()` is called, the actual validation rules executed are determined using both of the following criteria:

Carsten Brandt committed
222 223
- the rule must be associated with at least one active attribute;
- the rule must be active for the current scenario.
Alexander Makarov committed
224 225


226 227 228
### Creating your own validators (Inline validators)

If none of the built in validators fit your needs, you can create your own validator by creating a method in you model class.
229 230
This method will be wrapped by an [[yii\validators\InlineValidator|InlineValidator]] an be called upon validation.
You will do the validation of the attribute and [[yii\base\Model::addError()|add errors]] to the model when validation fails.
231 232 233 234 235 236 237 238

The method has the following signature `public function myValidator($attribute, $params)` while you are free to choose the name.

Here is an example implementation of a validator validating the age of a user:

```php
public function validateAge($attribute, $params)
{
239 240 241 242
    $value = $this->$attribute;
    if (strtotime($value) > strtotime('now - ' . $params['min'] . ' years')) {
        $this->addError($attribute, 'You must be at least ' . $params['min'] . ' years old to register for this service.');
    }
243 244 245 246
}

public function rules()
{
247 248 249 250
    return [
        // ...
        [['birthdate'], 'validateAge', 'params' => ['min' => '12']],
    ];
251 252 253
}
```

254 255
You may also set other properties of the [[yii\validators\InlineValidator|InlineValidator]] in the rules definition,
for example the [[yii\validators\InlineValidator::$skipOnEmpty|skipOnEmpty]] property:
256 257 258 259 260

```php
[['birthdate'], 'validateAge', 'params' => ['min' => '12'], 'skipOnEmpty' => false],
```

261
### Conditional validation
262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288

To validate attributes only when certain conditions apply, e.g. the validation of
one field depends on the value of another field you can use [[yii\validators\Validator::when|the `when` property]]
to define such conditions:

```php
['state', 'required', 'when' => function($model) { return $model->country == Country::USA; }],
['stateOthers', 'required', 'when' => function($model) { return $model->country != Country::USA; }],
['mother', 'required', 'when' => function($model) { return $model->age < 18 && $model->married != true; }],
```

For better readability the conditions can also be written like this:

```php
public function rules()
{
    $usa = function($model) { return $model->country == Country::USA; };
    $notUsa = function($model) { return $model->country != Country::USA; };
    $child = function($model) { return $model->age < 18 && $model->married != true; };
    return [
        ['state', 'required', 'when' => $usa],
        ['stateOthers', 'required', 'when' => $notUsa], // note that it is not possible to write !$usa
        ['mother', 'required', 'when' => $child],
    ];
}
```

289

Alexander Makarov committed
290 291 292 293 294 295 296 297
Massive Attribute Retrieval and Assignment
------------------------------------------

Attributes can be massively retrieved via the `attributes` property.
The following code will return *all* attributes in the `$post` model
as an array of name-value pairs.

```php
Alexander Makarov committed
298 299
$post = Post::find(42);
if ($post) {
300 301
    $attributes = $post->attributes;
    var_dump($attributes);
Alexander Makarov committed
302
}
Alexander Makarov committed
303 304 305 306 307
```

Using the same `attributes` property you can massively assign data from associative array to model attributes:

```php
Alexander Makarov committed
308
$post = new Post();
Alexander Makarov committed
309
$attributes = [
310 311
    'title' => 'Massive assignment example',
    'content' => 'Never allow assigning attributes that are not meant to be assigned.',
Alexander Makarov committed
312
];
Alexander Makarov committed
313 314
$post->attributes = $attributes;
var_dump($attributes);
Alexander Makarov committed
315 316
```

Carsten Brandt committed
317
In the code above we're assigning corresponding data to model attributes named as array keys. The key difference from mass
Alexander Makarov committed
318 319 320
retrieval that always works for all attributes is that in order to be assigned an attribute should be **safe** else
it will be ignored.

Carsten Brandt committed
321

Alexander Makarov committed
322 323 324 325 326 327 328 329
Validation rules and mass assignment
------------------------------------

In Yii2 unlike Yii 1.x validation rules are separated from mass assignment. Validation
rules are described in `rules()` method of the model while what's safe for mass
assignment is described in `scenarios` method:

```php
Alexander Makarov committed
330
class User extends ActiveRecord
Alexander Makarov committed
331
{
332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352
    public function rules()
    {
        return [
            // rule applied when corresponding field is "safe"
            ['username', 'string', 'length' => [4, 32]],
            ['first_name', 'string', 'max' => 128],
            ['password', 'required'],

            // rule applied when scenario is "signup" no matter if field is "safe" or not
            ['hashcode', 'check', 'on' => 'signup'],
        ];
    }

    public function scenarios()
    {
        return [
            // on signup allow mass assignment of username
            'signup' => ['username', 'password'],
            'update' => ['username', 'first_name'],
        ];
    }
Alexander Makarov committed
353
}
Alexander Makarov committed
354 355
```

356
For the code above mass assignment will be allowed strictly according to `scenarios()`:
Alexander Makarov committed
357 358 359 360 361

```php
$user = User::find(42);
$data = ['password' => '123'];
$user->attributes = $data;
362
print_r($user->attributes);
Alexander Makarov committed
363 364 365 366 367 368 369 370
```

Will give you empty array because there's no default scenario defined in our `scenarios()`.

```php
$user = User::find(42);
$user->scenario = 'signup';
$data = [
371 372 373
    'username' => 'samdark',
    'password' => '123',
    'hashcode' => 'test',
Alexander Makarov committed
374 375
];
$user->attributes = $data;
376
print_r($user->attributes);
Alexander Makarov committed
377 378 379 380 381 382
```

Will give you the following:

```php
array(
383 384 385 386
    'username' => 'samdark',
    'first_name' => null,
    'password' => '123',
    'hashcode' => null, // it's not defined in scenarios method
Alexander Makarov committed
387 388 389 390
)
```

In case of not defined `scenarios` method like the following:
Alexander Makarov committed
391

Alexander Makarov committed
392 393
```php
class User extends ActiveRecord
Alexander Makarov committed
394
{
395 396 397 398 399 400 401 402
    public function rules()
    {
        return [
            ['username', 'string', 'length' => [4, 32]],
            ['first_name', 'string', 'max' => 128],
            ['password', 'required'],
        ];
    }
Alexander Makarov committed
403 404 405
}
```

Alexander Makarov committed
406 407 408 409 410
The code above assumes default scenario so mass assignment will be available for all fields with `rules` defined:

```php
$user = User::find(42);
$data = [
411 412 413 414
    'username' => 'samdark',
    'first_name' => 'Alexander',
    'last_name' => 'Makarov',
    'password' => '123',
Alexander Makarov committed
415 416
];
$user->attributes = $data;
417
print_r($user->attributes);
Alexander Makarov committed
418 419 420
```

Will give you the following:
Alexander Makarov committed
421

Alexander Makarov committed
422 423
```php
array(
424 425 426
    'username' => 'samdark',
    'first_name' => 'Alexander',
    'password' => '123',
Alexander Makarov committed
427 428
)
```
Carsten Brandt committed
429

Alexander Makarov committed
430
If you want some fields to be unsafe for default scenario:
431 432 433 434

```php
class User extends ActiveRecord
{
435 436 437 438 439 440 441 442 443 444 445 446 447 448 449
    function rules()
    {
        return [
            ['username', 'string', 'length' => [4, 32]],
            ['first_name', 'string', 'max' => 128],
            ['password', 'required'],
        ];
    }

    public function scenarios()
    {
        return [
            self::SCENARIO_DEFAULT => ['username', 'first_name', '!password']
        ];
    }
450 451 452 453 454 455 456 457
}
```

Mass assignment is still available by default:

```php
$user = User::find(42);
$data = [
458 459 460
    'username' => 'samdark',
    'first_name' => 'Alexander',
    'password' => '123',
461 462
];
$user->attributes = $data;
Alexander Makarov committed
463
print_r($user->attributes);
464 465 466 467 468 469
```

The code above gives you:

```php
array(
470 471 472
    'username' => 'samdark',
    'first_name' => 'Alexander',
    'password' => null, // because of ! before field name in scenarios
473 474 475
)
```

Alexander Makarov committed
476 477 478 479
See also
--------

- [Model validation reference](validation.md)
480
- [[yii\base\Model]]