Yii源码阅读笔记（十四）

Model类，集中整个应用的数据和业务逻辑——场景、属性和标签：

  /**
      * Returns a list of scenarios and the corresponding active attributes.
      * An active attribute is one that is subject to validation in the current scenario.
      * 返回所有场景及与之对应的 active 属性的列表
      * active 属性是指在默认场景中验证的
      * The returned array should be in the following format:
      * 返回的格式如下：
      * ```php
      * [
      *     'scenario1' => ['attribute11', 'attribute12', ...],
      *     'scenario2' => ['attribute21', 'attribute22', ...],
      *     ...
      * ]
      * ```
      *
      * By default, an active attribute is considered safe and can be massively assigned.
      * 默认情况下，一个active属性被认为是安全的，可以被批量赋值
      * If an attribute should NOT be massively assigned (thus considered unsafe),
      * 如果不允许批量赋值，则在属性名称前面加“！”
      * please prefix the attribute with an exclamation character (e.g. `'!rank'`).
      *
      * The default implementation of this method will return all scenarios found in the [[rules()]]
      * declaration. A special scenario named [[SCENARIO_DEFAULT]] will contain all attributes
      * found in the [[rules()]]. Each scenario will be associated with the attributes that
      * are being validated by the validation rules that apply to the scenario.
      * 默认情况下会返回[[rules()]]中定义的所有场景，其中[[SCENARIO_DEFAULT]] 默认场景包含所有的属性
      * 每个场景对应的属性值将按指定的验证规则验证
      *
      * @return array a list of scenarios and the corresponding active attributes.
      */
     public function scenarios()
     {
         // 默认情况下有default 的场景
         $scenarios = [self::SCENARIO_DEFAULT => []];
         foreach ($this->getValidators() as $validator) {
             // 遍历validator，取出所有提到的场景，包括 on 和 except
             foreach ($validator->on as $scenario) {
                 $scenarios[$scenario] = [];
             }
             foreach ($validator->except as $scenario) {
                 $scenarios[$scenario] = [];
             }
         }
         // 取出所有场景的名称
         $names = array_keys($scenarios);

         foreach ($this->getValidators() as $validator) {
             if (empty($validator->on) && empty($validator->except)) {
                 // 如果 validator 即没有定义 on，也没有定义 except，就放到所有的场景中
                 foreach ($names as $name) {
                     // 循环 $validator 的所有属性
                     foreach ($validator->attributes as $attribute) {
                         $scenarios[$name][$attribute] = true;
                     }
                 }
             } elseif (empty($validator->on)) {
                 // 如果没有定义 on
                 foreach ($names as $name) {
                     if (!in_array($name, $validator->except, true)) {
                         // 而且场景不在 except 中， 就将这个属性加入到相应的场景中
                         foreach ($validator->attributes as $attribute) {
                             $scenarios[$name][$attribute] = true;
                         }
                     }
                 }
             } else {
                 // 如果定义了 on
                 foreach ($validator->on as $name) {
                     // 就将这个属性加入到 on 定义的场景中
                     foreach ($validator->attributes as $attribute) {
                         $scenarios[$name][$attribute] = true;
                     }
                 }
             }
         }

         /**
          * 将 $scenarios 从
          *
          * ~~~
          * [
          *     'default' => [],
          *     'scenario1' => ['attribute11' => true, 'attribute12' => true, ...],
          *     'scenario2' => ['attribute21' => true, 'attribute22' => true, ...],
          *     'scenario3' => [],
          *     ...
          * ]
          * ~~~
          * 转化为
          * ~~~
          * [
          *     'default' => [],
          *     'scenario1' => ['attribute11', 'attribute12', ...],
          *     'scenario2' => ['attribute21', 'attribute22', ...],
          *     ...
          * ]
          * ~~~
          */
         foreach ($scenarios as $scenario => $attributes) {
             // 去除掉没有属性值的场景
             if (!empty($attributes)) {
                 // 取出场景中的属性名称
                 $scenarios[$scenario] = array_keys($attributes);
             }
         }

         return $scenarios;
     }

     /**
      * Returns the form name that this model class should use.
      *
      * 返回表单的名称，就是这个 model 的类名，类名即表名
      *
      * The form name is mainly used by [[\yii\widgets\ActiveForm]] to determine how to name
      * the input fields for the attributes in a model. If the form name is "A" and an attribute
      * name is "b", then the corresponding input name would be "A[b]". If the form name is
      * an empty string, then the input name would be "b".
      * 表单名称用于[[\yii\widgets\ActiveForm]]确定模型中的属性名对应的输入域的名称
      * 如果表单名为A，属性名为b，对应的输入名为A[b]，如果表单名为空，则输入名为b
      *
      * The purpose of the above naming schema is that for forms which contain multiple different models,
      * the attributes of each model are grouped in sub-arrays of the POST-data and it is easier to
      * differentiate between them.
      * 上述命名模式的目的是，对于包含多个不同模型的表单，每个模型的属性分组在对应的表单名下的数组，能更好的区分它们
      *
      * By default, this method returns the model class name (without the namespace part)
      * as the form name. You may override it when the model is used in different forms.
      * 默认情况下该方法返回不包含命名空间的类名称，可以通过重写使用别的表名
      *
      * @return string the form name of this model class.
      * @see load()
      */
     public function formName()
     {
         // ReflectionClass 类，是php内置的反射类，用于获取类的信息，包含了一个类的有关信息
         $reflector = new ReflectionClass($this);
         // 获取类的短名，就是不含命名空间（namespace）的那一部分
         return $reflector->getShortName();
     }

     /**
      * Returns the list of attribute names.
      * 返回属性名的列表
      *
      * By default, this method returns all public non-static properties of the class.
      * You may override this method to change the default behavior.
      * 默认只会返回 public 且不是 static 的属性，可以重写该方法定义不同的返回类型
      *
      * @return array list of attribute names.
      */
     public function attributes()
     {
         $class = new ReflectionClass($this);
         $names = [];
         /**
          *ReflectionClass::getProperties — ReflectionClass反射类的方法，用于获取一组属性，有下列参数：
           ReflectionProperty::IS_STATIC 表示返回 static 的属性。
           ReflectionProperty::IS_PUBLIC 表示返回 public 的属性。
           ReflectionProperty::IS_PROTECTED 表示返回 protected 的属性。
           ReflectionProperty::IS_PRIVATE 表示返回 private 的属性。
          */
         foreach ($class->getProperties(\ReflectionProperty::IS_PUBLIC) as $property) {
             // 如果是public的属性，并且不是static的，就认为是它的attribute
             if (!$property->isStatic()) {
                 // 获取该属性的名称
                 $names[] = $property->getName();
             }
         }

         return $names;
     }

     /**
      * Returns the attribute labels.
      * 返回属性的标签
      *
      * Attribute labels are mainly used for display purpose. For example, given an attribute
      * `firstName`, we can declare a label `First Name` which is more user-friendly and can
      * be displayed to end users.
      * 属性标签主要用于显示目的，例如给属性'firstName'一个‘First Name’标签，能够更友好的显示给最终用户
      *
      * By default an attribute label is generated using [[generateAttributeLabel()]].
      * This method allows you to explicitly specify attribute labels.
      * 默认调用[[generateAttributeLabel()]]方法生成标签
      * Note, in order to inherit labels defined in the parent class, a child class needs to
      * merge the parent labels with child labels using functions such as `array_merge()`.
      * 注意，为了继承父类的标签，之类需要调用`array_merge()`合并父类的标签
      *
      * @return array attribute labels (name => label)
      * @see generateAttributeLabel()
      */
     public function attributeLabels()
     {
         return [];
     }