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

Larry Ullman committed
4 5
In keeping with the MVC approach, a model in Yii is intended for storing or temporarily representing application data, as well as defining the busines rules by which the data must abide.

Alexander Makarov committed
6
Yii models have the following basic features:
Alexander Makarov committed
7

Larry Ullman committed
8 9 10 11
- 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
12

13
Models in Yii extend from the [[yii\base\Model]] class. Models are typically used to both hold data and define
Alexander Makarov committed
14 15 16 17 18
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
19 20 21 22

Attributes
----------

23 24 25
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
26 27

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

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

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

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

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

59 60
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
61
that is associated with the class.
Alexander Makarov committed
62 63


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

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

71
To declare attribute labels, override the [[yii\base\Model::attributeLabels()]] method. The overridden method returns
Alexander Makarov committed
72
a mapping of attribute names to attribute labels, as shown in the example below. If an attribute is not found
73 74
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
75
`orderNumber` to `Order Number`).
Alexander Makarov committed
76 77 78 79 80

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

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

Scenarios
---------

97
A model may be used in different *scenarios*. For example, a `User` model may be used to collect user login inputs,
Alexander Makarov committed
98 99
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.
100 101 102 103

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
104 105 106

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,
107
additional attributes such as `email` are *active*. When an attribute is *active* this means that it is subject to validation.
Alexander Makarov committed
108

109 110
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
111 112 113 114

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

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

128 129 130 131
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
{
132 133 134 135 136 137 138
    public function scenarios()
    {
        $scenarios = parent::scenarios();
        $scenarios['login'] = ['username', 'password'];
        $scenarios['register'] = ['username', 'email', 'password'];
        return $scenarios;
    }
139 140 141 142
}
```


143 144
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
145 146

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

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

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

```php
class EmployeeController extends \yii\web\Controller
{
158 159 160 161 162 163 164 165 166 167 168 169 170 171 172
    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';
        }
    }
173 174 175
}
```

176
The example above presumes that the model is based upon [Active Record](active-record.md). For basic form models,
Alexander Makarov committed
177 178 179
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.
180

181

Alexander Makarov committed
182 183 184 185 186 187 188 189 190
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
191
$model = new LoginForm();
Alexander Makarov committed
192 193 194
$model->username = $_POST['username'];
$model->password = $_POST['password'];
if ($model->validate()) {
195
    // ... login the user ...
Alexander Makarov committed
196
} else {
197 198
    $errors = $model->getErrors();
    // ... display the errors to the end user ...
Alexander Makarov committed
199 200 201 202 203
}
```

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
204
instance of a [[yii\validators\Validator]] child class, or an array with the following format:
Alexander Makarov committed
205 206

```php
Alexander Makarov committed
207
[
208 209 210 211 212 213 214 215 216 217
    ['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
218
]
Alexander Makarov committed
219 220 221 222
```

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

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


227 228 229
### 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.
230 231
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.
232 233 234 235 236 237 238 239

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)
{
240 241 242 243
    $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.');
    }
244 245 246 247
}

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

255 256
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:
257 258 259 260 261

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

262
### Conditional validation
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 289

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],
    ];
}
```

290

Alexander Makarov committed
291 292 293 294 295 296 297 298
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
299
$post = Post::findOne(42);
Alexander Makarov committed
300
if ($post) {
301 302
    $attributes = $post->attributes;
    var_dump($attributes);
Alexander Makarov committed
303
}
Alexander Makarov committed
304 305 306 307 308
```

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

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

Carsten Brandt committed
318
In the code above we're assigning corresponding data to model attributes named as array keys. The key difference from mass
Alexander Makarov committed
319 320 321
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
322

Alexander Makarov committed
323 324 325 326 327 328 329 330
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
331
class User extends ActiveRecord
Alexander Makarov committed
332
{
333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353
    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
354
}
Alexander Makarov committed
355 356
```

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

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

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

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

Will give you the following:

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

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

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

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

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

Will give you the following:
Alexander Makarov committed
422

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

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

```php
class User extends ActiveRecord
{
436 437 438 439 440 441 442 443 444 445 446 447 448 449 450
    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']
        ];
    }
451 452 453 454 455 456
}
```

Mass assignment is still available by default:

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

The code above gives you:

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

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

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