yii2源码学习笔记(十三）

  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 <qiang.xue@gmail.com>
 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 }