模型類DynamicModel主要用於實現模型內的數據驗證yii2\base\DynamicModel.php
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 namespace yii\base;
8
9 use yii\validators\Validator;
10
11 /**
12 * DynamicModel is a model class primarily used to support ad hoc data validation.
13 * DynamicModel是一種主要用於支持ad hoc數據驗證模型類
14 * The typical usage of DynamicModel is as follows,
15 *
16 * ```php
17 * public function actionSearch($name, $email)
18 * {
19 * $model = DynamicModel::validateData(compact('name', 'email'), [
20 * [['name', 'email'], 'string', 'max' => 128],
21 * ['email', 'email'],
22 * ]);
23 * if ($model->hasErrors()) {
24 * // validation fails
25 * } else {
26 * // validation succeeds
27 * }
28 * }
29 * ```
30 *
31 * The above example shows how to validate `$name` and `$email` with the help of DynamicModel.
32 * 上面的例子演示了如何用DynamicModel驗證用戶名`$name`和郵箱`$email`
33 * The [[validateData()]] method creates an instance of DynamicModel, defines the attributes
34 * using the given data (`name` and `email` in this example), and then calls [[Model::validate()]].
35 * validateData() 方法會創建一個 DynamicModel 的實例對象。通過給定數據定義模型特性，之後調用Model::validate() 方法。
36 * You can check the validation result by [[hasErrors()]], like you do with a normal model.
37 * You may also access the dynamic attributes defined through the model instance, e.g.,
38 * 可以通過[[hasErrors()]]方法獲取驗證結果
39 * `$model->name` and `$model->email`.
40 *
41 * Alternatively, you may use the following more "classic" syntax to perform ad-hoc data validation:
42 * 除此之外，你也可以用如下的更加“classic（傳統）”的語法來執行臨時數據驗
43 * ```php
44 * $model = new DynamicModel(compact('name', 'email'));
45 * $model->addRule(['name', 'email'], 'string', ['max' => 128])
46 * ->addRule('email', 'email')
47 * ->validate();
48 * ```
49 *
50 * DynamicModel implements the above ad-hoc data validation feature by supporting the so-called
51 * "dynamic attributes". It basically allows an attribute to be defined dynamically through its constructor
52 * or [[defineAttribute()]].
53 * 實現了上述特殊數據模型驗證功能支持的“動態屬性”。允許通過它的構造函數或 [[defineAttribute()]]來定義一個屬性
54 * @author Qiang Xue <[email protected]>
55 * @since 2.0
56 */
57 class DynamicModel extends Model
58 {
59 private $_attributes = [];//動態模型內動態屬性
60
61
62 /**
63 * Constructors.構造函數，用於將傳入的屬性賦值給_attributes，便於使用
64 * @param array $attributes the dynamic attributes (name-value pairs, or names) being defined被定義的動態屬性
65 * @param array $config the configuration array to be applied to this object.用於該對象的配置數組。
66 */
67 public function __construct(array $attributes = [], $config = [])
68 {
69 foreach ($attributes as $name => $value) {//遍歷傳入的屬性
70 if (is_integer($name)) {//如果是整型，說明只傳入了屬性名，將屬性名寫入_attributes
71 $this->_attributes[$value] = null;
72 } else {
73 $this->_attributes[$name] = $value;//按鍵值對的形式寫入
74 }
75 }
76 parent::__construct($config);//調用父類的配置
77 }
78
79 /**
80 * @inheritdoc 重寫__get方法，從_attributes中取值
81 */
82 public function __get($name)
83 {
84 if (array_key_exists($name, $this->_attributes)) {
85 //如果傳入的$name在數組_attributes中存在，則從_attributes中取值
86 return $this->_attributes[$name];
87 } else {//否則調用父類的__get方法取屬性值
88 return parent::__get($name);
89 }
90 }
91
92 /**
93 * @inheritdoc 重寫__set方法，給_attributes設置值
94 */
95 public function __set($name, $value)
96 {
97 if (array_key_exists($name, $this->_attributes)) {
98 //如果傳入的$name在數組_attributes中存在，則將動態屬性$name的值設置為$value
99 $this->_attributes[$name] = $value;
100 } else {
101 parent::__set($name, $value);//調用父類的__set方法設置屬性值
102 }
103 }
104
105 /**
106 * @inheritdoc 同上 重寫__isset方法，判斷_attributes中是否設置$name值
107 */
108 public function __isset($name)
109 {
110 if (array_key_exists($name, $this->_attributes)) {
111 return isset($this->_attributes[$name]);
112 } else {
113 return parent::__isset($name);
114 }
115 }
116
117 /**
118 * @inheritdoc 同上，重寫__unset方法，刪除_attributes中的$name屬性值
119 */
120 public function __unset($name)
121 {
122 if (array_key_exists($name, $this->_attributes)) {
123 unset($this->_attributes[$name]);
124 } else {
125 parent::__unset($name);
126 }
127 }
128
129 /**
130 * Defines an attribute. 定義動態屬性的方法
131 * @param string $name the attribute name 屬性名
132 * @param mixed $value the attribute value 屬性值
133 */
134 public function defineAttribute($name, $value = null)
135 {
136 $this->_attributes[$name] = $value;
137 }
138
139 /**
140 * Undefines an attribute. 用於刪除動態屬性的方法
141 * @param string $name the attribute name 屬性名
142 */
143 public function undefineAttribute($name)
144 {
145 unset($this->_attributes[$name]);
146 }
147
148 /**
149 * Adds a validation rule to this model. 添加驗證規則
150 * You can also directly manipulate [[validators]] to add or remove validation rules.
151 * This method provides a shortcut.
152 * 可以直接調用[[validators]]來添加或者刪除驗證規則，本方法提供了一個短方法
153 * @param string|array $attributes the attribute(s) to be validated by the rule 進行驗證的屬性
154 * @param mixed $validator the validator for the rule.This can be a built-in validator name,
155 * a method name of the model class, an anonymous function, or a validator class name.
156 * 規則的驗證。這是一個內置驗證器的名字， 一個模型類的方法名，一個匿名函數或一個驗證器類的名稱。
157 * @param array $options the options (name-value pairs) to be applied to the validator
158 * (name-value)被應用到驗證器
159 * @return static the model itself 模型本身
160 */
161 public function addRule($attributes, $validator, $options = [])
162 {
163 $validators = $this->getValidators();//所有的驗證規則對象
164 //生成Validator對象，並且插入 $validators中
165 $validators->append(Validator::createValidator($validator, $this, (array) $attributes, $options));
166
167 return $this;
168 }
169
170 /**
171 * Validates the given data with the specified validation rules.通過指定的規則驗證給定的數據
172 * This method will create a DynamicModel instance, populate it with the data to be validated,
173 * create the specified validation rules, and then validate the data using these rules.
174 * @param array $data the data (name-value pairs) to be validated
175 * @param array $rules the validation rules. Please refer to [[Model::rules()]] on the format of this parameter.
176 * @return static the model instance that contains the data being validated
177 * @throws InvalidConfigException if a validation rule is not specified correctly.
178 */
179 public static function validateData(array $data, $rules = [])
180 {
181 /* @var $model DynamicModel */
182 $model = new static($data);//實例化調用類，將$data賦值給_attributes
183 if (!empty($rules)) {
184 $validators = $model->getValidators();//獲取所有定義的驗證規則
185 foreach ($rules as $rule) {
186 if ($rule instanceof Validator) {
187 $validators->append($rule);//如果$rule是Validator的實例，則添加到$validators中
188 } elseif (is_array($rule) && isset($rule[0], $rule[1])) { // attributes, validator type
189 //如果$rule是數組，則判斷動態屬性和驗證類型是否存在，創建Validator對象，添加到$validators中
190 $validator = Validator::createValidator($rule[1], $model, (array) $rule[0], array_slice($rule, 2));
191 $validators->append($validator);
192 } else {//拋出異常
193 throw new InvalidConfigException('Invalid validation rule: a rule must specify both attribute names and validator type.');
194 }
195 }
196 }
197
198 $model->validate();//執行驗證
199
200 return $model;
201 }
202
203 /**
204 * @inheritdoc 返回所有的動態屬性
205 */
206 public function attributes()
207 {
208 return array_keys($this->_attributes);
209 }
210 }
