These results are based on our legacy PHP analysis, consider migrating to our new PHP analysis engine instead. Learn more
1 | <?php |
||
2 | /** |
||
3 | * @link http://www.yiiframework.com/ |
||
4 | * @copyright Copyright (c) 2008 Yii Software LLC |
||
5 | * @license http://www.yiiframework.com/license/ |
||
6 | */ |
||
7 | |||
8 | namespace yii\base; |
||
9 | |||
10 | use ArrayAccess; |
||
11 | use ArrayIterator; |
||
12 | use ArrayObject; |
||
13 | use IteratorAggregate; |
||
14 | use ReflectionClass; |
||
15 | use Yii; |
||
16 | use yii\helpers\Inflector; |
||
17 | use yii\validators\RequiredValidator; |
||
18 | use yii\validators\Validator; |
||
19 | |||
20 | /** |
||
21 | * Model is the base class for data models. |
||
22 | * |
||
23 | * Model implements the following commonly used features: |
||
24 | * |
||
25 | * - attribute declaration: by default, every public class member is considered as |
||
26 | * a model attribute |
||
27 | * - attribute labels: each attribute may be associated with a label for display purpose |
||
28 | * - massive attribute assignment |
||
29 | * - scenario-based validation |
||
30 | * |
||
31 | * Model also raises the following events when performing data validation: |
||
32 | * |
||
33 | * - [[EVENT_BEFORE_VALIDATE]]: an event raised at the beginning of [[validate()]] |
||
34 | * - [[EVENT_AFTER_VALIDATE]]: an event raised at the end of [[validate()]] |
||
35 | * |
||
36 | * You may directly use Model to store model data, or extend it with customization. |
||
37 | * |
||
38 | * For more details and usage information on Model, see the [guide article on models](guide:structure-models). |
||
39 | * |
||
40 | * @property \yii\validators\Validator[] $activeValidators The validators applicable to the current |
||
41 | * [[scenario]]. This property is read-only. |
||
42 | * @property array $attributes Attribute values (name => value). |
||
43 | * @property array $errors An array of errors for all attributes. Empty array is returned if no error. The |
||
44 | * result is a two-dimensional array. See [[getErrors()]] for detailed description. This property is read-only. |
||
45 | * @property array $firstErrors The first errors. The array keys are the attribute names, and the array values |
||
46 | * are the corresponding error messages. An empty array will be returned if there is no error. This property is |
||
47 | * read-only. |
||
48 | * @property ArrayIterator $iterator An iterator for traversing the items in the list. This property is |
||
49 | * read-only. |
||
50 | * @property string $scenario The scenario that this model is in. Defaults to [[SCENARIO_DEFAULT]]. |
||
51 | * @property ArrayObject|\yii\validators\Validator[] $validators All the validators declared in the model. |
||
52 | * This property is read-only. |
||
53 | * |
||
54 | * @author Qiang Xue <[email protected]> |
||
55 | * @since 2.0 |
||
56 | */ |
||
57 | class Model extends Component implements StaticInstanceInterface, IteratorAggregate, ArrayAccess, Arrayable |
||
58 | { |
||
59 | use ArrayableTrait; |
||
60 | use StaticInstanceTrait; |
||
61 | |||
62 | /** |
||
63 | * The name of the default scenario. |
||
64 | */ |
||
65 | const SCENARIO_DEFAULT = 'default'; |
||
66 | /** |
||
67 | * @event ModelEvent an event raised at the beginning of [[validate()]]. You may set |
||
68 | * [[ModelEvent::isValid]] to be false to stop the validation. |
||
69 | */ |
||
70 | const EVENT_BEFORE_VALIDATE = 'beforeValidate'; |
||
71 | /** |
||
72 | * @event Event an event raised at the end of [[validate()]] |
||
73 | */ |
||
74 | const EVENT_AFTER_VALIDATE = 'afterValidate'; |
||
75 | |||
76 | /** |
||
77 | * @var array validation errors (attribute name => array of errors) |
||
78 | */ |
||
79 | private $_errors; |
||
80 | /** |
||
81 | * @var ArrayObject list of validators |
||
82 | */ |
||
83 | private $_validators; |
||
84 | /** |
||
85 | * @var string current scenario |
||
86 | */ |
||
87 | private $_scenario = self::SCENARIO_DEFAULT; |
||
88 | |||
89 | |||
90 | /** |
||
91 | * Returns the validation rules for attributes. |
||
92 | * |
||
93 | * Validation rules are used by [[validate()]] to check if attribute values are valid. |
||
94 | * Child classes may override this method to declare different validation rules. |
||
95 | * |
||
96 | * Each rule is an array with the following structure: |
||
97 | * |
||
98 | * ```php |
||
99 | * [ |
||
100 | * ['attribute1', 'attribute2'], |
||
101 | * 'validator type', |
||
102 | * 'on' => ['scenario1', 'scenario2'], |
||
103 | * //...other parameters... |
||
104 | * ] |
||
105 | * ``` |
||
106 | * |
||
107 | * where |
||
108 | * |
||
109 | * - attribute list: required, specifies the attributes array to be validated, for single attribute you can pass a string; |
||
110 | * - validator type: required, specifies the validator to be used. It can be a built-in validator name, |
||
111 | * a method name of the model class, an anonymous function, or a validator class name. |
||
112 | * - on: optional, specifies the [[scenario|scenarios]] array in which the validation |
||
113 | * rule can be applied. If this option is not set, the rule will apply to all scenarios. |
||
114 | * - additional name-value pairs can be specified to initialize the corresponding validator properties. |
||
115 | * Please refer to individual validator class API for possible properties. |
||
116 | * |
||
117 | * A validator can be either an object of a class extending [[Validator]], or a model class method |
||
118 | * (called *inline validator*) that has the following signature: |
||
119 | * |
||
120 | * ```php |
||
121 | * // $params refers to validation parameters given in the rule |
||
122 | * function validatorName($attribute, $params) |
||
123 | * ``` |
||
124 | * |
||
125 | * In the above `$attribute` refers to the attribute currently being validated while `$params` contains an array of |
||
126 | * validator configuration options such as `max` in case of `string` validator. The value of the attribute currently being validated |
||
127 | * can be accessed as `$this->$attribute`. Note the `$` before `attribute`; this is taking the value of the variable |
||
128 | * `$attribute` and using it as the name of the property to access. |
||
129 | * |
||
130 | * Yii also provides a set of [[Validator::builtInValidators|built-in validators]]. |
||
131 | * Each one has an alias name which can be used when specifying a validation rule. |
||
132 | * |
||
133 | * Below are some examples: |
||
134 | * |
||
135 | * ```php |
||
136 | * [ |
||
137 | * // built-in "required" validator |
||
138 | * [['username', 'password'], 'required'], |
||
139 | * // built-in "string" validator customized with "min" and "max" properties |
||
140 | * ['username', 'string', 'min' => 3, 'max' => 12], |
||
141 | * // built-in "compare" validator that is used in "register" scenario only |
||
142 | * ['password', 'compare', 'compareAttribute' => 'password2', 'on' => 'register'], |
||
143 | * // an inline validator defined via the "authenticate()" method in the model class |
||
144 | * ['password', 'authenticate', 'on' => 'login'], |
||
145 | * // a validator of class "DateRangeValidator" |
||
146 | * ['dateRange', 'DateRangeValidator'], |
||
147 | * ]; |
||
148 | * ``` |
||
149 | * |
||
150 | * Note, in order to inherit rules defined in the parent class, a child class needs to |
||
151 | * merge the parent rules with child rules using functions such as `array_merge()`. |
||
152 | * |
||
153 | * @return array validation rules |
||
154 | * @see scenarios() |
||
155 | */ |
||
156 | 110 | public function rules() |
|
157 | { |
||
158 | 110 | return []; |
|
159 | } |
||
160 | |||
161 | /** |
||
162 | * Returns a list of scenarios and the corresponding active attributes. |
||
163 | * |
||
164 | * An active attribute is one that is subject to validation in the current scenario. |
||
165 | * The returned array should be in the following format: |
||
166 | * |
||
167 | * ```php |
||
168 | * [ |
||
169 | * 'scenario1' => ['attribute11', 'attribute12', ...], |
||
170 | * 'scenario2' => ['attribute21', 'attribute22', ...], |
||
171 | * ... |
||
172 | * ] |
||
173 | * ``` |
||
174 | * |
||
175 | * By default, an active attribute is considered safe and can be massively assigned. |
||
176 | * If an attribute should NOT be massively assigned (thus considered unsafe), |
||
177 | * please prefix the attribute with an exclamation character (e.g. `'!rank'`). |
||
178 | * |
||
179 | * The default implementation of this method will return all scenarios found in the [[rules()]] |
||
180 | * declaration. A special scenario named [[SCENARIO_DEFAULT]] will contain all attributes |
||
181 | * found in the [[rules()]]. Each scenario will be associated with the attributes that |
||
182 | * are being validated by the validation rules that apply to the scenario. |
||
183 | * |
||
184 | * @return array a list of scenarios and the corresponding active attributes. |
||
185 | */ |
||
186 | 120 | public function scenarios() |
|
187 | { |
||
188 | 120 | $scenarios = [self::SCENARIO_DEFAULT => []]; |
|
189 | 120 | foreach ($this->getValidators() as $validator) { |
|
190 | 59 | foreach ($validator->on as $scenario) { |
|
191 | 6 | $scenarios[$scenario] = []; |
|
192 | } |
||
193 | 59 | foreach ($validator->except as $scenario) { |
|
194 | 59 | $scenarios[$scenario] = []; |
|
195 | } |
||
196 | } |
||
197 | 120 | $names = array_keys($scenarios); |
|
198 | |||
199 | 120 | foreach ($this->getValidators() as $validator) { |
|
200 | 59 | if (empty($validator->on) && empty($validator->except)) { |
|
201 | 59 | foreach ($names as $name) { |
|
202 | 59 | foreach ($validator->attributes as $attribute) { |
|
203 | 59 | $scenarios[$name][$attribute] = true; |
|
204 | } |
||
205 | } |
||
206 | 6 | } elseif (empty($validator->on)) { |
|
207 | 2 | foreach ($names as $name) { |
|
208 | 2 | if (!in_array($name, $validator->except, true)) { |
|
209 | 2 | foreach ($validator->attributes as $attribute) { |
|
210 | 2 | $scenarios[$name][$attribute] = true; |
|
211 | } |
||
212 | } |
||
213 | } |
||
214 | } else { |
||
215 | 6 | foreach ($validator->on as $name) { |
|
216 | 6 | foreach ($validator->attributes as $attribute) { |
|
217 | 59 | $scenarios[$name][$attribute] = true; |
|
218 | } |
||
219 | } |
||
220 | } |
||
221 | } |
||
222 | |||
223 | 120 | foreach ($scenarios as $scenario => $attributes) { |
|
224 | 120 | if (!empty($attributes)) { |
|
225 | 120 | $scenarios[$scenario] = array_keys($attributes); |
|
226 | } |
||
227 | } |
||
228 | |||
229 | 120 | return $scenarios; |
|
230 | } |
||
231 | |||
232 | /** |
||
233 | * Returns the form name that this model class should use. |
||
234 | * |
||
235 | * The form name is mainly used by [[\yii\widgets\ActiveForm]] to determine how to name |
||
236 | * the input fields for the attributes in a model. If the form name is "A" and an attribute |
||
237 | * name is "b", then the corresponding input name would be "A[b]". If the form name is |
||
238 | * an empty string, then the input name would be "b". |
||
239 | * |
||
240 | * The purpose of the above naming schema is that for forms which contain multiple different models, |
||
241 | * the attributes of each model are grouped in sub-arrays of the POST-data and it is easier to |
||
242 | * differentiate between them. |
||
243 | * |
||
244 | * By default, this method returns the model class name (without the namespace part) |
||
245 | * as the form name. You may override it when the model is used in different forms. |
||
246 | * |
||
247 | * @return string the form name of this model class. |
||
248 | * @see load() |
||
249 | * @throws InvalidConfigException when form is defined with anonymous class and `formName()` method is |
||
250 | * not overridden. |
||
251 | */ |
||
252 | 69 | public function formName() |
|
253 | { |
||
254 | 69 | $reflector = new ReflectionClass($this); |
|
255 | 69 | if (PHP_VERSION_ID >= 70000 && $reflector->isAnonymous()) { |
|
256 | 1 | throw new InvalidConfigException('The "formName()" method should be explicitly defined for anonymous models'); |
|
257 | } |
||
258 | 68 | return $reflector->getShortName(); |
|
259 | } |
||
260 | |||
261 | /** |
||
262 | * Returns the list of attribute names. |
||
263 | * By default, this method returns all public non-static properties of the class. |
||
264 | * You may override this method to change the default behavior. |
||
265 | * @return array list of attribute names. |
||
266 | */ |
||
267 | 5 | public function attributes() |
|
268 | { |
||
269 | 5 | $class = new ReflectionClass($this); |
|
270 | 5 | $names = []; |
|
271 | 5 | foreach ($class->getProperties(\ReflectionProperty::IS_PUBLIC) as $property) { |
|
272 | 5 | if (!$property->isStatic()) { |
|
273 | 5 | $names[] = $property->getName(); |
|
274 | } |
||
275 | } |
||
276 | |||
277 | 5 | return $names; |
|
278 | } |
||
279 | |||
280 | /** |
||
281 | * Returns the attribute labels. |
||
282 | * |
||
283 | * Attribute labels are mainly used for display purpose. For example, given an attribute |
||
284 | * `firstName`, we can declare a label `First Name` which is more user-friendly and can |
||
285 | * be displayed to end users. |
||
286 | * |
||
287 | * By default an attribute label is generated using [[generateAttributeLabel()]]. |
||
288 | * This method allows you to explicitly specify attribute labels. |
||
289 | * |
||
290 | * Note, in order to inherit labels defined in the parent class, a child class needs to |
||
291 | * merge the parent labels with child labels using functions such as `array_merge()`. |
||
292 | * |
||
293 | * @return array attribute labels (name => label) |
||
294 | * @see generateAttributeLabel() |
||
295 | */ |
||
296 | 83 | public function attributeLabels() |
|
297 | { |
||
298 | 83 | return []; |
|
299 | } |
||
300 | |||
301 | /** |
||
302 | * Returns the attribute hints. |
||
303 | * |
||
304 | * Attribute hints are mainly used for display purpose. For example, given an attribute |
||
305 | * `isPublic`, we can declare a hint `Whether the post should be visible for not logged in users`, |
||
306 | * which provides user-friendly description of the attribute meaning and can be displayed to end users. |
||
307 | * |
||
308 | * Unlike label hint will not be generated, if its explicit declaration is omitted. |
||
309 | * |
||
310 | * Note, in order to inherit hints defined in the parent class, a child class needs to |
||
311 | * merge the parent hints with child hints using functions such as `array_merge()`. |
||
312 | * |
||
313 | * @return array attribute hints (name => hint) |
||
314 | * @since 2.0.4 |
||
315 | */ |
||
316 | 4 | public function attributeHints() |
|
317 | { |
||
318 | 4 | return []; |
|
319 | } |
||
320 | |||
321 | /** |
||
322 | * Performs the data validation. |
||
323 | * |
||
324 | * This method executes the validation rules applicable to the current [[scenario]]. |
||
325 | * The following criteria are used to determine whether a rule is currently applicable: |
||
326 | * |
||
327 | * - the rule must be associated with the attributes relevant to the current scenario; |
||
328 | * - the rules must be effective for the current scenario. |
||
329 | * |
||
330 | * This method will call [[beforeValidate()]] and [[afterValidate()]] before and |
||
331 | * after the actual validation, respectively. If [[beforeValidate()]] returns false, |
||
332 | * the validation will be cancelled and [[afterValidate()]] will not be called. |
||
333 | * |
||
334 | * Errors found during the validation can be retrieved via [[getErrors()]], |
||
335 | * [[getFirstErrors()]] and [[getFirstError()]]. |
||
336 | * |
||
337 | * @param string[]|string $attributeNames attribute name or list of attribute names that should be validated. |
||
338 | * If this parameter is empty, it means any attribute listed in the applicable |
||
339 | * validation rules should be validated. |
||
340 | * @param bool $clearErrors whether to call [[clearErrors()]] before performing validation |
||
341 | * @return bool whether the validation is successful without any error. |
||
342 | * @throws InvalidArgumentException if the current scenario is unknown. |
||
343 | */ |
||
344 | 83 | public function validate($attributeNames = null, $clearErrors = true) |
|
345 | { |
||
346 | 83 | if ($clearErrors) { |
|
347 | 74 | $this->clearErrors(); |
|
348 | } |
||
349 | |||
350 | 83 | if (!$this->beforeValidate()) { |
|
351 | return false; |
||
352 | } |
||
353 | |||
354 | 83 | $scenarios = $this->scenarios(); |
|
355 | 83 | $scenario = $this->getScenario(); |
|
356 | 83 | if (!isset($scenarios[$scenario])) { |
|
357 | throw new InvalidArgumentException("Unknown scenario: $scenario"); |
||
358 | } |
||
359 | |||
360 | 83 | if ($attributeNames === null) { |
|
361 | 83 | $attributeNames = $this->activeAttributes(); |
|
362 | } |
||
363 | |||
364 | 83 | $attributeNames = (array)$attributeNames; |
|
365 | |||
366 | 83 | foreach ($this->getActiveValidators() as $validator) { |
|
367 | 43 | $validator->validateAttributes($this, $attributeNames); |
|
368 | } |
||
369 | 83 | $this->afterValidate(); |
|
370 | |||
371 | 83 | return !$this->hasErrors(); |
|
372 | } |
||
373 | |||
374 | /** |
||
375 | * This method is invoked before validation starts. |
||
376 | * The default implementation raises a `beforeValidate` event. |
||
377 | * You may override this method to do preliminary checks before validation. |
||
378 | * Make sure the parent implementation is invoked so that the event can be raised. |
||
379 | * @return bool whether the validation should be executed. Defaults to true. |
||
380 | * If false is returned, the validation will stop and the model is considered invalid. |
||
381 | */ |
||
382 | 84 | public function beforeValidate() |
|
383 | { |
||
384 | 84 | $event = new ModelEvent(); |
|
385 | 84 | $this->trigger(self::EVENT_BEFORE_VALIDATE, $event); |
|
386 | |||
387 | 84 | return $event->isValid; |
|
388 | } |
||
389 | |||
390 | /** |
||
391 | * This method is invoked after validation ends. |
||
392 | * The default implementation raises an `afterValidate` event. |
||
393 | * You may override this method to do postprocessing after validation. |
||
394 | * Make sure the parent implementation is invoked so that the event can be raised. |
||
395 | */ |
||
396 | 83 | public function afterValidate() |
|
397 | { |
||
398 | 83 | $this->trigger(self::EVENT_AFTER_VALIDATE); |
|
399 | 83 | } |
|
400 | |||
401 | /** |
||
402 | * Returns all the validators declared in [[rules()]]. |
||
403 | * |
||
404 | * This method differs from [[getActiveValidators()]] in that the latter |
||
405 | * only returns the validators applicable to the current [[scenario]]. |
||
406 | * |
||
407 | * Because this method returns an ArrayObject object, you may |
||
408 | * manipulate it by inserting or removing validators (useful in model behaviors). |
||
409 | * For example, |
||
410 | * |
||
411 | * ```php |
||
412 | * $model->validators[] = $newValidator; |
||
413 | * ``` |
||
414 | * |
||
415 | * @return ArrayObject|\yii\validators\Validator[] all the validators declared in the model. |
||
416 | */ |
||
417 | 135 | public function getValidators() |
|
418 | { |
||
419 | 135 | if ($this->_validators === null) { |
|
420 | 135 | $this->_validators = $this->createValidators(); |
|
421 | } |
||
422 | |||
423 | 135 | return $this->_validators; |
|
424 | } |
||
425 | |||
426 | /** |
||
427 | * Returns the validators applicable to the current [[scenario]]. |
||
428 | * @param string $attribute the name of the attribute whose applicable validators should be returned. |
||
429 | * If this is null, the validators for ALL attributes in the model will be returned. |
||
430 | * @return \yii\validators\Validator[] the validators applicable to the current [[scenario]]. |
||
431 | */ |
||
432 | 116 | public function getActiveValidators($attribute = null) |
|
433 | { |
||
434 | 116 | $activeAttributes = $this->activeAttributes(); |
|
435 | 116 | if ($attribute !== null && !in_array($attribute, $activeAttributes, true)) { |
|
436 | 22 | return []; |
|
437 | } |
||
438 | 96 | $scenario = $this->getScenario(); |
|
439 | 96 | $validators = []; |
|
440 | 96 | foreach ($this->getValidators() as $validator) { |
|
441 | 56 | if ($attribute === null) { |
|
442 | 44 | $validatorAttributes = $validator->getValidationAttributes($activeAttributes); |
|
443 | 44 | $attributeValid = !empty($validatorAttributes); |
|
444 | } else { |
||
445 | 13 | $attributeValid = in_array($attribute, $validator->getValidationAttributes($attribute), true); |
|
446 | } |
||
447 | 56 | if ($attributeValid && $validator->isActive($scenario)) { |
|
448 | 56 | $validators[] = $validator; |
|
449 | } |
||
450 | } |
||
451 | |||
452 | 96 | return $validators; |
|
453 | } |
||
454 | |||
455 | /** |
||
456 | * Creates validator objects based on the validation rules specified in [[rules()]]. |
||
457 | * Unlike [[getValidators()]], each time this method is called, a new list of validators will be returned. |
||
458 | * @return ArrayObject validators |
||
459 | * @throws InvalidConfigException if any validation rule configuration is invalid |
||
460 | */ |
||
461 | 136 | public function createValidators() |
|
462 | { |
||
463 | 136 | $validators = new ArrayObject(); |
|
464 | 136 | foreach ($this->rules() as $rule) { |
|
465 | 50 | if ($rule instanceof Validator) { |
|
466 | $validators->append($rule); |
||
467 | 50 | } elseif (is_array($rule) && isset($rule[0], $rule[1])) { // attributes, validator type |
|
468 | 49 | $validator = Validator::createValidator($rule[1], $this, (array) $rule[0], array_slice($rule, 2)); |
|
469 | 49 | $validators->append($validator); |
|
470 | } else { |
||
471 | 50 | throw new InvalidConfigException('Invalid validation rule: a rule must specify both attribute names and validator type.'); |
|
472 | } |
||
473 | } |
||
474 | |||
475 | 135 | return $validators; |
|
476 | } |
||
477 | |||
478 | /** |
||
479 | * Returns a value indicating whether the attribute is required. |
||
480 | * This is determined by checking if the attribute is associated with a |
||
481 | * [[\yii\validators\RequiredValidator|required]] validation rule in the |
||
482 | * current [[scenario]]. |
||
483 | * |
||
484 | * Note that when the validator has a conditional validation applied using |
||
485 | * [[\yii\validators\RequiredValidator::$when|$when]] this method will return |
||
486 | * `false` regardless of the `when` condition because it may be called be |
||
487 | * before the model is loaded with data. |
||
488 | * |
||
489 | * @param string $attribute attribute name |
||
490 | * @return bool whether the attribute is required |
||
491 | */ |
||
492 | 25 | public function isAttributeRequired($attribute) |
|
493 | { |
||
494 | 25 | foreach ($this->getActiveValidators($attribute) as $validator) { |
|
495 | 5 | if ($validator instanceof RequiredValidator && $validator->when === null) { |
|
496 | 5 | return true; |
|
497 | } |
||
498 | } |
||
499 | |||
500 | 22 | return false; |
|
501 | } |
||
502 | |||
503 | /** |
||
504 | * Returns a value indicating whether the attribute is safe for massive assignments. |
||
505 | * @param string $attribute attribute name |
||
506 | * @return bool whether the attribute is safe for massive assignments |
||
507 | * @see safeAttributes() |
||
508 | */ |
||
509 | 18 | public function isAttributeSafe($attribute) |
|
510 | { |
||
511 | 18 | return in_array($attribute, $this->safeAttributes(), true); |
|
512 | } |
||
513 | |||
514 | /** |
||
515 | * Returns a value indicating whether the attribute is active in the current scenario. |
||
516 | * @param string $attribute attribute name |
||
517 | * @return bool whether the attribute is active in the current scenario |
||
518 | * @see activeAttributes() |
||
519 | */ |
||
520 | 2 | public function isAttributeActive($attribute) |
|
521 | { |
||
522 | 2 | return in_array($attribute, $this->activeAttributes(), true); |
|
523 | } |
||
524 | |||
525 | /** |
||
526 | * Returns the text label for the specified attribute. |
||
527 | * @param string $attribute the attribute name |
||
528 | * @return string the attribute label |
||
529 | * @see generateAttributeLabel() |
||
530 | * @see attributeLabels() |
||
531 | */ |
||
532 | 40 | public function getAttributeLabel($attribute) |
|
533 | { |
||
534 | 40 | $labels = $this->attributeLabels(); |
|
535 | 40 | return isset($labels[$attribute]) ? $labels[$attribute] : $this->generateAttributeLabel($attribute); |
|
536 | } |
||
537 | |||
538 | /** |
||
539 | * Returns the text hint for the specified attribute. |
||
540 | * @param string $attribute the attribute name |
||
541 | * @return string the attribute hint |
||
542 | * @see attributeHints() |
||
543 | * @since 2.0.4 |
||
544 | */ |
||
545 | 12 | public function getAttributeHint($attribute) |
|
546 | { |
||
547 | 12 | $hints = $this->attributeHints(); |
|
548 | 12 | return isset($hints[$attribute]) ? $hints[$attribute] : ''; |
|
549 | } |
||
550 | |||
551 | /** |
||
552 | * Returns a value indicating whether there is any validation error. |
||
553 | * @param string|null $attribute attribute name. Use null to check all attributes. |
||
554 | * @return bool whether there is any error. |
||
555 | */ |
||
556 | 346 | public function hasErrors($attribute = null) |
|
557 | { |
||
558 | 346 | return $attribute === null ? !empty($this->_errors) : isset($this->_errors[$attribute]); |
|
559 | } |
||
560 | |||
561 | /** |
||
562 | * Returns the errors for all attributes or a single attribute. |
||
563 | * @param string $attribute attribute name. Use null to retrieve errors for all attributes. |
||
564 | * @property array An array of errors for all attributes. Empty array is returned if no error. |
||
565 | * The result is a two-dimensional array. See [[getErrors()]] for detailed description. |
||
566 | * @return array errors for all attributes or the specified attribute. Empty array is returned if no error. |
||
567 | * Note that when returning errors for all attributes, the result is a two-dimensional array, like the following: |
||
568 | * |
||
569 | * ```php |
||
570 | * [ |
||
571 | * 'username' => [ |
||
572 | * 'Username is required.', |
||
573 | * 'Username must contain only word characters.', |
||
574 | * ], |
||
575 | * 'email' => [ |
||
576 | * 'Email address is invalid.', |
||
577 | * ] |
||
578 | * ] |
||
579 | * ``` |
||
580 | * |
||
581 | * @see getFirstErrors() |
||
582 | * @see getFirstError() |
||
583 | */ |
||
584 | 44 | public function getErrors($attribute = null) |
|
585 | { |
||
586 | 44 | if ($attribute === null) { |
|
587 | 9 | return $this->_errors === null ? [] : $this->_errors; |
|
588 | } |
||
589 | |||
590 | 36 | return isset($this->_errors[$attribute]) ? $this->_errors[$attribute] : []; |
|
591 | } |
||
592 | |||
593 | /** |
||
594 | * Returns the first error of every attribute in the model. |
||
595 | * @return array the first errors. The array keys are the attribute names, and the array |
||
596 | * values are the corresponding error messages. An empty array will be returned if there is no error. |
||
597 | * @see getErrors() |
||
598 | * @see getFirstError() |
||
599 | */ |
||
600 | 8 | public function getFirstErrors() |
|
601 | { |
||
602 | 8 | if (empty($this->_errors)) { |
|
603 | 3 | return []; |
|
604 | } |
||
605 | |||
606 | 6 | $errors = []; |
|
607 | 6 | foreach ($this->_errors as $name => $es) { |
|
608 | 6 | if (!empty($es)) { |
|
609 | 6 | $errors[$name] = reset($es); |
|
610 | } |
||
611 | } |
||
612 | |||
613 | 6 | return $errors; |
|
614 | } |
||
615 | |||
616 | /** |
||
617 | * Returns the first error of the specified attribute. |
||
618 | * @param string $attribute attribute name. |
||
619 | * @return string the error message. Null is returned if no error. |
||
620 | * @see getErrors() |
||
621 | * @see getFirstErrors() |
||
622 | */ |
||
623 | 34 | public function getFirstError($attribute) |
|
624 | { |
||
625 | 34 | return isset($this->_errors[$attribute]) ? reset($this->_errors[$attribute]) : null; |
|
626 | } |
||
627 | |||
628 | /** |
||
629 | * Returns the errors for all attributes as a one-dimensional array. |
||
630 | * @param bool $showAllErrors boolean, if set to true every error message for each attribute will be shown otherwise |
||
631 | * only the first error message for each attribute will be shown. |
||
632 | * @return array errors for all attributes as a one-dimensional array. Empty array is returned if no error. |
||
633 | * @see getErrors() |
||
634 | * @see getFirstErrors() |
||
635 | * @since 2.0.14 |
||
636 | */ |
||
637 | 11 | public function getErrorSummary($showAllErrors) |
|
638 | { |
||
639 | 11 | $lines = []; |
|
640 | 11 | $errors = $showAllErrors ? $this->getErrors() : $this->getFirstErrors(); |
|
641 | 11 | foreach ($errors as $es) { |
|
642 | 9 | $lines = array_merge((array)$es, $lines); |
|
643 | } |
||
644 | 11 | return $lines; |
|
645 | } |
||
646 | |||
647 | /** |
||
648 | * Adds a new error to the specified attribute. |
||
649 | * @param string $attribute attribute name |
||
650 | * @param string $error new error message |
||
651 | */ |
||
652 | 124 | public function addError($attribute, $error = '') |
|
653 | { |
||
654 | 124 | $this->_errors[$attribute][] = $error; |
|
655 | 124 | } |
|
656 | |||
657 | /** |
||
658 | * Adds a list of errors. |
||
659 | * @param array $items a list of errors. The array keys must be attribute names. |
||
660 | * The array values should be error messages. If an attribute has multiple errors, |
||
661 | * these errors must be given in terms of an array. |
||
662 | * You may use the result of [[getErrors()]] as the value for this parameter. |
||
663 | * @since 2.0.2 |
||
664 | */ |
||
665 | 8 | public function addErrors(array $items) |
|
666 | { |
||
667 | 8 | foreach ($items as $attribute => $errors) { |
|
668 | 8 | if (is_array($errors)) { |
|
669 | 8 | foreach ($errors as $error) { |
|
670 | 8 | $this->addError($attribute, $error); |
|
671 | } |
||
672 | } else { |
||
673 | 8 | $this->addError($attribute, $errors); |
|
674 | } |
||
675 | } |
||
676 | 8 | } |
|
677 | |||
678 | /** |
||
679 | * Removes errors for all attributes or a single attribute. |
||
680 | * @param string $attribute attribute name. Use null to remove errors for all attributes. |
||
681 | */ |
||
682 | 107 | public function clearErrors($attribute = null) |
|
683 | { |
||
684 | 107 | if ($attribute === null) { |
|
685 | 100 | $this->_errors = []; |
|
686 | } else { |
||
687 | 12 | unset($this->_errors[$attribute]); |
|
688 | } |
||
689 | 107 | } |
|
690 | |||
691 | /** |
||
692 | * Generates a user friendly attribute label based on the give attribute name. |
||
693 | * This is done by replacing underscores, dashes and dots with blanks and |
||
694 | * changing the first letter of each word to upper case. |
||
695 | * For example, 'department_name' or 'DepartmentName' will generate 'Department Name'. |
||
696 | * @param string $name the column name |
||
697 | * @return string the attribute label |
||
698 | */ |
||
699 | 94 | public function generateAttributeLabel($name) |
|
700 | { |
||
701 | 94 | return Inflector::camel2words($name, true); |
|
702 | } |
||
703 | |||
704 | /** |
||
705 | * Returns attribute values. |
||
706 | * @param array $names list of attributes whose value needs to be returned. |
||
707 | * Defaults to null, meaning all attributes listed in [[attributes()]] will be returned. |
||
708 | * If it is an array, only the attributes in the array will be returned. |
||
709 | * @param array $except list of attributes whose value should NOT be returned. |
||
710 | * @return array attribute values (name => value). |
||
711 | */ |
||
712 | 5 | public function getAttributes($names = null, $except = []) |
|
713 | { |
||
714 | 5 | $values = []; |
|
715 | 5 | if ($names === null) { |
|
716 | 5 | $names = $this->attributes(); |
|
717 | } |
||
718 | 5 | foreach ($names as $name) { |
|
719 | 5 | $values[$name] = $this->$name; |
|
720 | } |
||
721 | 5 | foreach ($except as $name) { |
|
722 | 1 | unset($values[$name]); |
|
723 | } |
||
724 | |||
725 | 5 | return $values; |
|
726 | } |
||
727 | |||
728 | /** |
||
729 | * Sets the attribute values in a massive way. |
||
730 | * @param array $values attribute values (name => value) to be assigned to the model. |
||
731 | * @param bool $safeOnly whether the assignments should only be done to the safe attributes. |
||
732 | * A safe attribute is one that is associated with a validation rule in the current [[scenario]]. |
||
733 | * @see safeAttributes() |
||
734 | * @see attributes() |
||
735 | */ |
||
736 | 14 | public function setAttributes($values, $safeOnly = true) |
|
737 | { |
||
738 | 14 | if (is_array($values)) { |
|
739 | 14 | $attributes = array_flip($safeOnly ? $this->safeAttributes() : $this->attributes()); |
|
740 | 14 | foreach ($values as $name => $value) { |
|
741 | 14 | if (isset($attributes[$name])) { |
|
742 | 14 | $this->$name = $value; |
|
743 | 3 | } elseif ($safeOnly) { |
|
744 | 14 | $this->onUnsafeAttribute($name, $value); |
|
745 | } |
||
746 | } |
||
747 | } |
||
748 | 14 | } |
|
749 | |||
750 | /** |
||
751 | * This method is invoked when an unsafe attribute is being massively assigned. |
||
752 | * The default implementation will log a warning message if YII_DEBUG is on. |
||
753 | * It does nothing otherwise. |
||
754 | * @param string $name the unsafe attribute name |
||
755 | * @param mixed $value the attribute value |
||
756 | */ |
||
757 | 3 | public function onUnsafeAttribute($name, $value) |
|
0 ignored issues
–
show
|
|||
758 | { |
||
759 | 3 | if (YII_DEBUG) { |
|
760 | 3 | Yii::debug("Failed to set unsafe attribute '$name' in '" . get_class($this) . "'.", __METHOD__); |
|
761 | } |
||
762 | 3 | } |
|
763 | |||
764 | /** |
||
765 | * Returns the scenario that this model is used in. |
||
766 | * |
||
767 | * Scenario affects how validation is performed and which attributes can |
||
768 | * be massively assigned. |
||
769 | * |
||
770 | * @return string the scenario that this model is in. Defaults to [[SCENARIO_DEFAULT]]. |
||
771 | */ |
||
772 | 214 | public function getScenario() |
|
773 | { |
||
774 | 214 | return $this->_scenario; |
|
775 | } |
||
776 | |||
777 | /** |
||
778 | * Sets the scenario for the model. |
||
779 | * Note that this method does not check if the scenario exists or not. |
||
780 | * The method [[validate()]] will perform this check. |
||
781 | * @param string $value the scenario that this model is in. |
||
782 | */ |
||
783 | 11 | public function setScenario($value) |
|
784 | { |
||
785 | 11 | $this->_scenario = $value; |
|
786 | 11 | } |
|
787 | |||
788 | /** |
||
789 | * Returns the attribute names that are safe to be massively assigned in the current scenario. |
||
790 | * @return string[] safe attribute names |
||
791 | */ |
||
792 | 26 | public function safeAttributes() |
|
793 | { |
||
794 | 26 | $scenario = $this->getScenario(); |
|
795 | 26 | $scenarios = $this->scenarios(); |
|
796 | 26 | if (!isset($scenarios[$scenario])) { |
|
797 | 3 | return []; |
|
798 | } |
||
799 | 26 | $attributes = []; |
|
800 | 26 | foreach ($scenarios[$scenario] as $attribute) { |
|
801 | 26 | if ($attribute[0] !== '!' && !in_array('!' . $attribute, $scenarios[$scenario])) { |
|
802 | 26 | $attributes[] = $attribute; |
|
803 | } |
||
804 | } |
||
805 | |||
806 | 26 | return $attributes; |
|
807 | } |
||
808 | |||
809 | /** |
||
810 | * Returns the attribute names that are subject to validation in the current scenario. |
||
811 | * @return string[] safe attribute names |
||
812 | */ |
||
813 | 118 | public function activeAttributes() |
|
814 | { |
||
815 | 118 | $scenario = $this->getScenario(); |
|
816 | 118 | $scenarios = $this->scenarios(); |
|
817 | 118 | if (!isset($scenarios[$scenario])) { |
|
818 | 3 | return []; |
|
819 | } |
||
820 | 118 | $attributes = array_keys(array_flip($scenarios[$scenario])); |
|
821 | 118 | foreach ($attributes as $i => $attribute) { |
|
822 | 60 | if ($attribute[0] === '!') { |
|
823 | 60 | $attributes[$i] = substr($attribute, 1); |
|
824 | } |
||
825 | } |
||
826 | |||
827 | 118 | return $attributes; |
|
828 | } |
||
829 | |||
830 | /** |
||
831 | * Populates the model with input data. |
||
832 | * |
||
833 | * This method provides a convenient shortcut for: |
||
834 | * |
||
835 | * ```php |
||
836 | * if (isset($_POST['FormName'])) { |
||
837 | * $model->attributes = $_POST['FormName']; |
||
838 | * if ($model->save()) { |
||
839 | * // handle success |
||
840 | * } |
||
841 | * } |
||
842 | * ``` |
||
843 | * |
||
844 | * which, with `load()` can be written as: |
||
845 | * |
||
846 | * ```php |
||
847 | * if ($model->load($_POST) && $model->save()) { |
||
848 | * // handle success |
||
849 | * } |
||
850 | * ``` |
||
851 | * |
||
852 | * `load()` gets the `'FormName'` from the model's [[formName()]] method (which you may override), unless the |
||
853 | * `$formName` parameter is given. If the form name is empty, `load()` populates the model with the whole of `$data`, |
||
854 | * instead of `$data['FormName']`. |
||
855 | * |
||
856 | * Note, that the data being populated is subject to the safety check by [[setAttributes()]]. |
||
857 | * |
||
858 | * @param array $data the data array to load, typically `$_POST` or `$_GET`. |
||
859 | * @param string $formName the form name to use to load the data into the model. |
||
860 | * If not set, [[formName()]] is used. |
||
861 | * @return bool whether `load()` found the expected form in `$data`. |
||
862 | */ |
||
863 | 4 | public function load($data, $formName = null) |
|
864 | { |
||
865 | 4 | $scope = $formName === null ? $this->formName() : $formName; |
|
866 | 4 | if ($scope === '' && !empty($data)) { |
|
867 | 3 | $this->setAttributes($data); |
|
868 | |||
869 | 3 | return true; |
|
870 | 3 | } elseif (isset($data[$scope])) { |
|
871 | 2 | $this->setAttributes($data[$scope]); |
|
872 | |||
873 | 2 | return true; |
|
874 | } |
||
875 | |||
876 | 3 | return false; |
|
877 | } |
||
878 | |||
879 | /** |
||
880 | * Populates a set of models with the data from end user. |
||
881 | * This method is mainly used to collect tabular data input. |
||
882 | * The data to be loaded for each model is `$data[formName][index]`, where `formName` |
||
883 | * refers to the value of [[formName()]], and `index` the index of the model in the `$models` array. |
||
884 | * If [[formName()]] is empty, `$data[index]` will be used to populate each model. |
||
885 | * The data being populated to each model is subject to the safety check by [[setAttributes()]]. |
||
886 | * @param array $models the models to be populated. Note that all models should have the same class. |
||
887 | * @param array $data the data array. This is usually `$_POST` or `$_GET`, but can also be any valid array |
||
888 | * supplied by end user. |
||
889 | * @param string $formName the form name to be used for loading the data into the models. |
||
890 | * If not set, it will use the [[formName()]] value of the first model in `$models`. |
||
891 | * This parameter is available since version 2.0.1. |
||
892 | * @return bool whether at least one of the models is successfully populated. |
||
893 | */ |
||
894 | 1 | public static function loadMultiple($models, $data, $formName = null) |
|
895 | { |
||
896 | 1 | if ($formName === null) { |
|
897 | /* @var $first Model|false */ |
||
898 | 1 | $first = reset($models); |
|
899 | 1 | if ($first === false) { |
|
900 | return false; |
||
901 | } |
||
902 | 1 | $formName = $first->formName(); |
|
903 | } |
||
904 | |||
905 | 1 | $success = false; |
|
906 | 1 | foreach ($models as $i => $model) { |
|
907 | /* @var $model Model */ |
||
908 | 1 | if ($formName == '') { |
|
909 | 1 | if (!empty($data[$i]) && $model->load($data[$i], '')) { |
|
910 | 1 | $success = true; |
|
911 | } |
||
912 | 1 | } elseif (!empty($data[$formName][$i]) && $model->load($data[$formName][$i], '')) { |
|
913 | 1 | $success = true; |
|
914 | } |
||
915 | } |
||
916 | |||
917 | 1 | return $success; |
|
918 | } |
||
919 | |||
920 | /** |
||
921 | * Validates multiple models. |
||
922 | * This method will validate every model. The models being validated may |
||
923 | * be of the same or different types. |
||
924 | * @param array $models the models to be validated |
||
925 | * @param array $attributeNames list of attribute names that should be validated. |
||
926 | * If this parameter is empty, it means any attribute listed in the applicable |
||
927 | * validation rules should be validated. |
||
928 | * @return bool whether all models are valid. False will be returned if one |
||
929 | * or multiple models have validation error. |
||
930 | */ |
||
931 | public static function validateMultiple($models, $attributeNames = null) |
||
932 | { |
||
933 | $valid = true; |
||
934 | /* @var $model Model */ |
||
935 | foreach ($models as $model) { |
||
936 | $valid = $model->validate($attributeNames) && $valid; |
||
937 | } |
||
938 | |||
939 | return $valid; |
||
940 | } |
||
941 | |||
942 | /** |
||
943 | * Returns the list of fields that should be returned by default by [[toArray()]] when no specific fields are specified. |
||
944 | * |
||
945 | * A field is a named element in the returned array by [[toArray()]]. |
||
946 | * |
||
947 | * This method should return an array of field names or field definitions. |
||
948 | * If the former, the field name will be treated as an object property name whose value will be used |
||
949 | * as the field value. If the latter, the array key should be the field name while the array value should be |
||
950 | * the corresponding field definition which can be either an object property name or a PHP callable |
||
951 | * returning the corresponding field value. The signature of the callable should be: |
||
952 | * |
||
953 | * ```php |
||
954 | * function ($model, $field) { |
||
955 | * // return field value |
||
956 | * } |
||
957 | * ``` |
||
958 | * |
||
959 | * For example, the following code declares four fields: |
||
960 | * |
||
961 | * - `email`: the field name is the same as the property name `email`; |
||
962 | * - `firstName` and `lastName`: the field names are `firstName` and `lastName`, and their |
||
963 | * values are obtained from the `first_name` and `last_name` properties; |
||
964 | * - `fullName`: the field name is `fullName`. Its value is obtained by concatenating `first_name` |
||
965 | * and `last_name`. |
||
966 | * |
||
967 | * ```php |
||
968 | * return [ |
||
969 | * 'email', |
||
970 | * 'firstName' => 'first_name', |
||
971 | * 'lastName' => 'last_name', |
||
972 | * 'fullName' => function ($model) { |
||
973 | * return $model->first_name . ' ' . $model->last_name; |
||
974 | * }, |
||
975 | * ]; |
||
976 | * ``` |
||
977 | * |
||
978 | * In this method, you may also want to return different lists of fields based on some context |
||
979 | * information. For example, depending on [[scenario]] or the privilege of the current application user, |
||
980 | * you may return different sets of visible fields or filter out some fields. |
||
981 | * |
||
982 | * The default implementation of this method returns [[attributes()]] indexed by the same attribute names. |
||
983 | * |
||
984 | * @return array the list of field names or field definitions. |
||
985 | * @see toArray() |
||
986 | */ |
||
987 | 2 | public function fields() |
|
988 | { |
||
989 | 2 | $fields = $this->attributes(); |
|
990 | |||
991 | 2 | return array_combine($fields, $fields); |
|
992 | } |
||
993 | |||
994 | /** |
||
995 | * Returns an iterator for traversing the attributes in the model. |
||
996 | * This method is required by the interface [[\IteratorAggregate]]. |
||
997 | * @return ArrayIterator an iterator for traversing the items in the list. |
||
998 | */ |
||
999 | 4 | public function getIterator() |
|
1000 | { |
||
1001 | 4 | $attributes = $this->getAttributes(); |
|
1002 | 4 | return new ArrayIterator($attributes); |
|
1003 | } |
||
1004 | |||
1005 | /** |
||
1006 | * Returns whether there is an element at the specified offset. |
||
1007 | * This method is required by the SPL interface [[\ArrayAccess]]. |
||
1008 | * It is implicitly called when you use something like `isset($model[$offset])`. |
||
1009 | * @param mixed $offset the offset to check on. |
||
1010 | * @return bool whether or not an offset exists. |
||
1011 | */ |
||
1012 | 1 | public function offsetExists($offset) |
|
1013 | { |
||
1014 | 1 | return isset($this->$offset); |
|
1015 | } |
||
1016 | |||
1017 | /** |
||
1018 | * Returns the element at the specified offset. |
||
1019 | * This method is required by the SPL interface [[\ArrayAccess]]. |
||
1020 | * It is implicitly called when you use something like `$value = $model[$offset];`. |
||
1021 | * @param mixed $offset the offset to retrieve element. |
||
1022 | * @return mixed the element at the offset, null if no element is found at the offset |
||
1023 | */ |
||
1024 | 192 | public function offsetGet($offset) |
|
1025 | { |
||
1026 | 192 | return $this->$offset; |
|
1027 | } |
||
1028 | |||
1029 | /** |
||
1030 | * Sets the element at the specified offset. |
||
1031 | * This method is required by the SPL interface [[\ArrayAccess]]. |
||
1032 | * It is implicitly called when you use something like `$model[$offset] = $item;`. |
||
1033 | * @param int $offset the offset to set element |
||
1034 | * @param mixed $item the element value |
||
1035 | */ |
||
1036 | 4 | public function offsetSet($offset, $item) |
|
1037 | { |
||
1038 | 4 | $this->$offset = $item; |
|
1039 | 4 | } |
|
1040 | |||
1041 | /** |
||
1042 | * Sets the element value at the specified offset to null. |
||
1043 | * This method is required by the SPL interface [[\ArrayAccess]]. |
||
1044 | * It is implicitly called when you use something like `unset($model[$offset])`. |
||
1045 | * @param mixed $offset the offset to unset element |
||
1046 | */ |
||
1047 | 1 | public function offsetUnset($offset) |
|
1048 | { |
||
1049 | 1 | $this->$offset = null; |
|
1050 | 1 | } |
|
1051 | } |
||
1052 |
This check looks from parameters that have been defined for a function or method, but which are not used in the method body.