namespace yii\base;

use yii\validators\Validator;

/**
 * DynamicModel is a model class primarily used to support ad hoc data validation.
 * DynamicModel是一种主要用于支持ad hoc数据验证模型类
 *
 * The typical usage of DynamicModel is as follows,
 * 典型用法如下：
 *
 * ```php
 * public function actionSearch($name, $email)
 * {
 *     $model = DynamicModel::validateData(compact('name', 'email'), [
 *         [['name', 'email'], 'string', 'max' => 128],
 *         ['email', 'email'],
 *     ]);
 *     if ($model->hasErrors()) {
 *         // validation fails
 *     } else {
 *         // validation succeeds
 *     }
 * }
 * ```
 *
 * The above example shows how to validate `$name` and `$email` with the help of DynamicModel.
 * 上面的例子演示了如何用DynamicModel验证用户名`$name`和邮箱`$email`
 * The [[validateData()]] method creates an instance of DynamicModel, defines the attributes
 * using the given data (`name` and `email` in this example), and then calls [[Model::validate()]].
 * yii\base\DynamicModel::validateData() 方法会创建一个 DynamicModel 的实例对象
 * 并通过给定数据定义模型特性（以 name 和email 为例），之后用给定规则调用 yii\base\Model::validate() 方法。
 *
 * You can check the validation result by [[hasErrors()]], like you do with a normal model.
 * 可以通过[[hasErrors()]]方法获取验证结果
 * You may also access the dynamic attributes defined through the model instance, e.g.,
 * `$model->name` and `$model->email`.
 *
 * Alternatively, you may use the following more "classic" syntax to perform ad-hoc data validation:
 * 除此之外呢，你也可以用如下的更加“传统”的语法来执行临时数据验证：
 *
 * ```php
 * $model = new DynamicModel(compact('name', 'email'));
 * $model->addRule(['name', 'email'], 'string', ['max' => 128])
 *     ->addRule('email', 'email')
 *     ->validate();
 * ```
 *
 * DynamicModel implements the above ad-hoc data validation feature by supporting the so-called
 * "dynamic attributes". It basically allows an attribute to be defined dynamically through its constructor
 * or [[defineAttribute()]].
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @since 2.0
 */
class DynamicModel extends Model
{
    /**
     * @var array 动态模型内动态属性
     */
    private $_attributes = [];

    /**
     * Constructors.
     * 构造函数，用于将传入的属性赋值给_attributes，便于使用
     * @param array $attributes the dynamic attributes (name-value pairs, or names) being defined
     * @param array $config the configuration array to be applied to this object.
     */
    public function __construct(array $attributes = [], $config = [])
    {
        foreach ($attributes as $name => $value) {//遍历传入的属性
            if (is_int($name)) {//如果$name是整型，说明只传入了属性名，将属性名写入_attributes
                $this->_attributes[$value] = null;
            } else {//否则，按键值对的形式写入
                $this->_attributes[$name] = $value;
            }
        }
        parent::__construct($config);//调用父类方法配置对象
    }

    /**
     * @inheritdoc  重写父类的__get方法，实现从_attributes中取值
     */
    public function __get($name)
    {
        if (array_key_exists($name, $this->_attributes)) {//如果传入的$name在_attributes中存在，则从_attributes中取值
            return $this->_attributes[$name];
        } else {//否则调用父类的__get方法取属性值
            return parent::__get($name);
        }
    }

    /**
     * @inheritdoc 重写父类的__set方法，实现给_attributes设置值
     */
    public function __set($name, $value)
    {
        if (array_key_exists($name, $this->_attributes)) {//如果传入的$name在_attributes中存在，则将动态属性$name的值设置为$value
            $this->_attributes[$name] = $value;
        } else {//否则调用父类的__set方法设置动态属性值
            parent::__set($name, $value);
        }
    }

    /**
     * @inheritdoc 同上，重写父类的__isset方法，实现判断_attributes中是否设置$name值
     */
    public function __isset($name)
    {
        if (array_key_exists($name, $this->_attributes)) {
            return isset($this->_attributes[$name]);
        } else {
            return parent::__isset($name);
        }
    }

    /**
     * @inheritdoc 同上，重写父类的__unset方法，实现注销_attributes中的$name动态属性值
     */
    public function __unset($name)
    {
        if (array_key_exists($name, $this->_attributes)) {
            unset($this->_attributes[$name]);
        } else {
            parent::__unset($name);
        }
    }

    /**
     * Defines an attribute.
     * 用于定义DynamicModel 的动态属性的方法
     * @param string $name the attribute name
     * @param mixed $value the attribute value
     */
    public function defineAttribute($name, $value = null)
    {
        $this->_attributes[$name] = $value;
    }

    /**
     * Undefines an attribute.
     * 用于注销DynamicModel 的动态属性的方法
     * @param string $name the attribute name
     */
    public function undefineAttribute($name)
    {
        unset($this->_attributes[$name]);
    }

    /**
     * Adds a validation rule to this model.
     * 添加验证规则
     * You can also directly manipulate [[validators]] to add or remove validation rules.
     * 可以直接调用[[validators]]来添加或者删除验证规则，本方法提供了一个短方法
     * This method provides a shortcut.
     * @param string|array $attributes the attribute(s) to be validated by the rule
     * @param mixed $validator the validator for the rule.This can be a built-in validator name,
     * a method name of the model class, an anonymous function, or a validator class name.
     * @param array $options the options (name-value pairs) to be applied to the validator
     * @return $this the model itself
     */
    public function addRule($attributes, $validator, $options = [])
    {
        $validators = $this->getValidators();//返回所有的验证规则对象
        //生成Validator对象，并且插入 $validators中
        $validators->append(Validator::createValidator($validator, $this, (array) $attributes, $options));

        return $this;
    }

    /**
     * Validates the given data with the specified validation rules.
     * 通过指定的规则验证给定的数据
     * This method will create a DynamicModel instance, populate it with the data to be validated,
     * create the specified validation rules, and then validate the data using these rules.
     * @param array $data the data (name-value pairs) to be validated
     * @param array $rules the validation rules. Please refer to [[Model::rules()]] on the format of this parameter.
     * @return static the model instance that contains the data being validated
     * @throws InvalidConfigException if a validation rule is not specified correctly.
     */
    public static function validateData(array $data, $rules = [])
    {
        /* @var $model DynamicModel */
        /* new static 用于实例化调用类  new self 用于实例化代码书写的那个类*/
        $model = new static($data);//实例化调用类，将$data赋值给_attributes
        if (!empty($rules)) {
            $validators = $model->getValidators();//获取所有定义的验证规则对象
            foreach ($rules as $rule) {//遍历传入的验证规则
                if ($rule instanceof Validator) {//如果$rule是Validator的实例，则添加到$validators中
                    $validators->append($rule);
                } elseif (is_array($rule) && isset($rule[0], $rule[1])) { // attributes, validator type
                   //如果$rule是数组，则判断动态属性和验证类型是否存在，存在怎创建Validator对象，添加到$validators中
                    $validator = Validator::createValidator($rule[1], $model, (array) $rule[0], array_slice($rule, 2));
                    $validators->append($validator);
                } else {//否则，抛出异常
                    throw new InvalidConfigException('Invalid validation rule: a rule must specify both attribute names and validator type.');
                }
            }
        }

        $model->validate();//执行验证

        return $model;
    }

    /**
     * @inheritdoc //返回所有的动态属性
     */
    public function attributes()
    {
        return array_keys($this->_attributes);
    }
}