Yii源码阅读笔记（十三）

  1 namespace yii\base;
  2 
  3 use Yii;
  4 use ArrayAccess;
  5 use ArrayObject;
  6 use ArrayIterator;
  7 use ReflectionClass;
  8 use IteratorAggregate;
  9 use yii\helpers\Inflector;
 10 use yii\validators\RequiredValidator;
 11 use yii\validators\Validator;
 12 
 13 /**
 14  * Model is the base class for data models.
 15  * Model是数据模型的基类
 16  * Model implements the following commonly used features:
 17  * 模型实现了以下常用的特性:
 18  *
 19  * - attribute declaration: by default, every public class member is considered as
 20  *   a model attribute
 21  *   属性声明:默认情况下,每一个公共类成员被认为是一个模型属性.
 22  * - attribute labels: each attribute may be associated with a label for display purpose
 23  *   属性标签:每个属性可能与一个标签显示的目的相关联
 24  * - massive attribute assignment
 25  *   大规模属性赋值
 26  * - scenario-based validation
 27  *   基于场景的验证
 28  *
 29  * Model also raises the following events when performing data validation:
 30  * Model在执行数据验证时会触发下面的事件：
 31  *
 32  * - [[EVENT_BEFORE_VALIDATE]]: an event raised at the beginning of [[validate()]]
 33  *   数据验证前的事件
 34  * - [[EVENT_AFTER_VALIDATE]]: an event raised at the end of [[validate()]]
 35  *   数据验证后的事件
 36  *
 37  * You may directly use Model to store model data, or extend it with customization.
 38  *  可以直接通过Model来实例化模型数据，也可以通过继承来自定义
 39  *
 40  * @property \yii\validators\Validator[] $activeValidators The validators applicable to the current
 41  * [[scenario]]. This property is read-only.
 42  * [[scenario]].默认场景名称，该属性是只读的
 43  * @property array $attributes Attribute values (name => value).
 44  * @property array $errors An array of errors for all attributes. Empty array is returned if no error. The
 45  * result is a two-dimensional array. See [[getErrors()]] for detailed description. This property is read-only.
 46  * 错误属性，保存所有属性的错误信息，无错误信息返回空，结果集为二维数组 只读
 47  * @property array $firstErrors The first errors. The array keys are the attribute names, and the array values
 48  * are the corresponding error messages. An empty array will be returned if there is no error. This property is
 49  * read-only.
 50  * 第一条错误信息，键名为属性值，键值为错误信息 只读
 51  * @property ArrayIterator $iterator An iterator for traversing the items in the list. This property is
 52  * read-only.
 53  *  迭代器属性，遍历列表中项目的迭代器
 54  * @property string $scenario The scenario that this model is in. Defaults to [[SCENARIO_DEFAULT]].
 55  *  场景属性
 56  * @property ArrayObject|\yii\validators\Validator[] $validators All the validators declared in the model.
 57  *  validators属性，模型中的所有验证方法 只读
 58  * This property is read-only.
 59  * @author Qiang Xue <qiang.xue@gmail.com>
 60  * @since 2.0
 61  */
 62 
 63 /**
 64  *  实现了IteratorAggregate, ArrayAccess, Arrayable三个接口API
 65  *  IteratorAggregate --PHP5提供的一种迭代（iteration）对象的功能API，就像使用数组那样，可以通过foreach 来遍历对象中的属性。
 66  *  默认情况下，在外部迭代只能得到外部可见的属性的值。
 67  *  ArrayAccess PHP的一个API，用来实现像数组一样来访问你的PHP对象
 68  */
 69 class Model extends Component implements IteratorAggregate, ArrayAccess, Arrayable
 70 {
 71     use ArrayableTrait;//使用ArrayableTrait，类似于继承了一个arrayable类
 72     //Trait 是一种为类似 PHP 的单继承语言而准备的代码复用机制，和一个类相似。
 73     //Trait 不能通过它自身来实例化。它为传统继承增加了水平特性的组合；也就是说，应用类的成员不需要继承。
 74     /**
 75      * The name of the default scenario.
 76      * 默认场景的名称
 77      */
 78     const SCENARIO_DEFAULT = ‘default‘;
 79     /**
 80      * @event ModelEvent an event raised at the beginning of [[validate()]]. You may set
 81      * [[ModelEvent::isValid]] to be false to stop the validation.
 82      * [[validate()]]开始前触发的事件常量，通过设置[[ModelEvent::isValid]]停用
 83      */
 84     const EVENT_BEFORE_VALIDATE = ‘beforeValidate‘;
 85     /**
 86      * @event Event an event raised at the end of [[validate()]]
 87      * [[validate()]]结束后触发的事件常量
 88      */
 89     const EVENT_AFTER_VALIDATE = ‘afterValidate‘;
 90 
 91     /**
 92      * @var array validation errors (attribute name => array of errors)
 93      * 验证的错误信息，键名为属性值，键值为错误信息
 94      */
 95     private $_errors;
 96     /**
 97      * @var ArrayObject list of validators
 98      *  验证方法validators的列表
 99      */
100     private $_validators;
101     /**
102      * @var 场景属性，默认值为self::SCENARIO_DEFAULT;
103      */
104     private $_scenario = self::SCENARIO_DEFAULT;
105 
106 
107     /**
108      * Returns the validation rules for attributes.
109      * 返回属性的验证规则
110      *
111      * Validation rules are used by [[validate()]] to check if attribute values are valid.
112      * [[validate()]] 方法调用用于验证属性有效性的验证规则
113      * Child classes may override this method to declare different validation rules.
114      * 子类通过重写此方法定义不同的验证规则
115      *
116      * Each rule is an array with the following structure:
117      * 定义格式如下：
118      *
119      * ```php
120      * [
121      *     [‘attribute1‘, ‘attribute2‘],//属性名称列表
122      *     ‘validator type‘,//验证的类型
123      *     ‘on‘ => [‘scenario1‘, ‘scenario2‘],//使用场景
124      *     //...other parameters...
125      * ]
126      * ```
127      *
128      * where
129      *
130      *  - attribute list: required, specifies the attributes array to be validated, for single attribute you can pass string;
131      *    属性名称列表:必选, 指定要验证的属性名称
132      *  - validator type: required, specifies the validator to be used. It can be a built-in validator name,
133      *    验证的类型: 必选, 指定将要使用的验证器. 可以示内置的验证方法名,
134      *    a method name of the model class, an anonymous function, or a validator class name.
135      *    模型model的一个方法，匿名函数，或者一个验证类的名称
136      *  - on: 选项, specifies the [[scenario|scenarios]] array in which the validation
137      *    rule can be applied. If this option is not set, the rule will apply to all scenarios.
138      *    on: 选项,指定应用场景
139      *  - additional name-value pairs can be specified to initialize the corresponding validator properties.
140      *    Please refer to individual validator class API for possible properties.
141      *    追加的参数
142      *
143      * A validator can be either an object of a class extending [[Validator]], or a model class method
144      * (called *inline validator*) that has the following signature:
145      * validator可以是[[Validator]]的一个实例，也可以是模型model的方法
146      *
147      * ```php
148      * // $params refers to validation parameters given in the rule
149      * //验证规则中引用的参数
150      * function validatorName($attribute, $params)
151      * ```
152      *
153      * In the above `$attribute` refers to the attribute currently being validated while `$params` contains an array of
154      * validator configuration options such as `max` in case of `string` validator. The value of the attribute currently being validated
155      * can be accessed as `$this->$attribute`. Note the `$` before `attribute`; this is taking the value of the variable
156      * `$attribute` and using it as the name of the property to access.
157      *
158      * Yii also provides a set of [[Validator::builtInValidators|built-in validators]].
159      * Each one has an alias name which can be used when specifying a validation rule.
160      * 下面是Yii提供的一些内置验证器
161      * Below are some examples:
162      *
163      * ```php
164      * [
165      *     // built-in "required" validator
166      *     [[‘username‘, ‘password‘], ‘required‘],
167      *     // built-in "string" validator customized with "min" and "max" properties
168      *     [‘username‘, ‘string‘, ‘min‘ => 3, ‘max‘ => 12],
169      *     // built-in "compare" validator that is used in "register" scenario only
170      *     [‘password‘, ‘compare‘, ‘compareAttribute‘ => ‘password2‘, ‘on‘ => ‘register‘],
171      *     // an inline validator defined via the "authenticate()" method in the model class
172      *     [‘password‘, ‘authenticate‘, ‘on‘ => ‘login‘],
173      *     // a validator of class "DateRangeValidator"
174      *     [‘dateRange‘, ‘DateRangeValidator‘],
175      * ];
176      * ```
177      *
178      * Note, in order to inherit rules defined in the parent class, a child class needs to
179      * merge the parent rules with child rules using functions such as `array_merge()`.
180      * 如果想继承父类中的验证规则，需要通过array_merge()函数合并验证规则数组
181      *
182      * @return array validation rules
183      * @see scenarios()
184      */
185     public function rules()
186     {
187         return [];
188     }