yii2源码学习笔记(二）

yii\base\Object代码详解

 <?php
 /**
  * @link http://www.yiiframework.com/
  * @copyright Copyright (c) 2008 Yii Software LLC
  * @license http://www.yiiframework.com/license/
  */

 namespace yii\base;

 use Yii;

 /**
  * Object is the base class that implements the *property* feature.
  * Object 是一个实现属性功能的基类
  * A property is defined by a getter method (e.g. `getLabel`), and/or a setter method (e.g. `setLabel`). For example,
  * 定义了getter和setter方法。例如：
  * the following getter and setter methods define a property named `label`:
  *
  * ~~~
  * private $_label;
  *
  * public function getLabel()
  * {
  *     return $this->_label;
  * }
  *
  * public function setLabel($value)
  * {
  *     $this->_label = $value;
  * }
  * ~~~
  *
  * Property names are *case-insensitive*.
  * 属性名大小写敏感
  * A property can be accessed like a member variable of an object. Reading or writing a property will cause the invocation
  * of the corresponding getter or setter method. For example,
  * 可以访问对象的属性，如对象的成员变量。读或写一个属性将导致调用相应的getter或setter方法
  * ~~~
  * // equivalent to $label = $object->getLabel();
  * $label = $object->label;
  * // equivalent to $object->setLabel('abc');
  * $object->label = 'abc';
  * ~~~
  *
  * If a property has only a getter method and has no setter method, it is considered as *read-only*. In this case, trying
  * to modify the property value will cause an exception.
  * 如果一个属性只有getter方法，就只能读，如果写会出现异常。
  * One can call [[hasProperty()]], [[canGetProperty()]] and/or [[canSetProperty()]] to check the existence of a property.
  * 通过hasProperty canGetProperty或canSetProperty 检查属性是否存在
  * Besides the property feature, Object also introduces an important object initialization life cycle. In particular,
  * creating an new instance of Object or its derived class will involve the following life cycles sequentially:
  * 除了属性特征，对象还引入了一个重要的对象初始化生命周期，
  * 创建一个新的对象或其派生类的实例，将涉及下列生命周期
  * 1. the class constructor is invoked;
  * 2. object properties are initialized according to the given configuration;
  * 3. the `init()` method is invoked.
  *  调用构造函数;
  *  根据给定的对象属性初始化配置;
  *  init()调用的方法.
  * In the above, both Step 2 and 3 occur at the end of the class constructor. It is recommended that
  * you perform object initialization in the `init()` method because at that stage, the object configuration
  * is already applied.
  * 2和3发生在类构造函数的末端。建议
  * 你完成对象的初始化在` init（）`方法因为在那个阶段，对象配置已经应用。
  * In order to ensure the above life cycles, if a child class of Object needs to override the constructor,
  * it should be done like the following:
  * 为了保证的生命周期，如果一个子类的对象需要重写构造函数，
  * ~~~
  * public function __construct($param1, $param2, ..., $config = [])
  * {
  *     ...
  *     parent::__construct($config);
  * }
  * ~~~
  *
  * That is, a `$config` parameter (defaults to `[]`) should be declared as the last parameter
  * of the constructor, and the parent implementation should be called at the end of the constructor.
  * 一个配置的参数应该声明为最后一个参数，构造函数和父类的实现应该在结尾调用
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @since 2.0
  */
 class Object
 {
     /**
      * Returns the fully qualified name of this class. 获取静态方法调用的类名，返回类的名称
      * @return string the fully qualified name of this class.
      */
     public static function className()
     {   //哪个类调用，就返回哪个类，
         return get_called_class();
     }

     /**
      * Constructor.
      * The default implementation does two things:
      *
      * - Initializes the object with the given configuration `$config`.
      * - Call [[init()]].
      *
      * If this method is overridden in a child class, it is recommended that
      *
      * - the last parameter of the constructor is a configuration array, like `$config` here.
      * - call the parent implementation at the end of the constructor.
      *
      * @param array $config name-value pairs that will be used to initialize the object properties
      */
     public function __construct($config = [])
     {
         //根据$config初始化对象
         if (!empty($config)) {
             Yii::configure($this, $config);
         }
         //调用 init（）方法，用于初始化，可以被重写。
         $this->init();
     }

     /**
      * Initializes the object.
      * This method is invoked at the end of the constructor after the object is initialized with the
      * given configuration.
      * 初始化结束时调用，与给定的配置初始化。
      */
     public function init()
     {
     }

     /**
      * Returns the value of an object property.
      *
      * Do not call this method directly as it is a PHP magic method that
      * will be implicitly called when executing `$value = $object->property;`.
      * 不要直接调用这个方法,因为它是一个PHP魔术方法，要隐式调用
      * @param string $name the property name 属性名称
      * @return mixed the property value      属性值
      * @throws UnknownPropertyException if the property is not defined 属性未定义
      * @throws InvalidCallException if the property is write-only   该属性写
      * @see __set()
      */
     public function __get($name)
     {
         $getter = 'get' . $name;//定义$getter
         if (method_exists($this, $getter)) {
             return $this->$getter();//存在方法，直接调用
         } elseif (method_exists($this, 'set' . $name)) {
             // 如果存在 'set' . $name 方法，就认为属性是只写
             throw new InvalidCallException('Getting write-only property: ' . get_class($this) . '::' . $name);
         } else {
             // 否则认为该属性不存在 未定义
             throw new UnknownPropertyException('Getting unknown property: ' . get_class($this) . '::' . $name);
         }
     }

     /**
      * Sets value of an object property.
      *
      * Do not call this method directly as it is a PHP magic method that
      * will be implicitly called when executing `$object->property = $value;`.
      * @param string $name the property name or the event name 属性或事件名称
      * @param mixed $value the property value   属性值
      * @throws UnknownPropertyException if the property is not defined 未定义属性
      * @throws InvalidCallException if the property is read-only    属性只写
      * @see __get()
      */
     public function __set($name, $value)
     {
         $setter = 'set' . $name;
         if (method_exists($this, $setter)) {
             $this->$setter($value);//对象存在$setter方法，直接调用
         } elseif (method_exists($this, 'get' . $name)) {
              // 存在 'get' . $name 方法，就认为该属性是只读
             throw new InvalidCallException('Setting read-only property: ' . get_class($this) . '::' . $name);
         } else {  // 否则认为该属性不存在 未定义
             throw new UnknownPropertyException('Setting unknown property: ' . get_class($this) . '::' . $name);
         }
     }

     /**
      * Checks if the named property is set (not null).
      * 检查属性是否设置
      * Do not call this method directly as it is a PHP magic method that
      * will be implicitly called when executing `isset($object->property)`.
      *
      * Note that if the property is not defined, false will be returned. 未定义返回false
      * @param string $name the property name or the event name  属性名
      * @return boolean whether the named property is set (not null).
      */
     public function __isset($name)
     {
         $getter = 'get' . $name;
         if (method_exists($this, $getter)) {
             //由$getter获取的值不为null，该属性存在，返回true
             return $this->$getter() !== null;
         } else {
             return false;//该属性存在，返回false
         }
     }

     /**
      * Sets an object property to null.
      * 设置一个属性为空
      * Do not call this method directly as it is a PHP magic method that
      * will be implicitly called when executing `unset($object->property)`.
      *
      * Note that if the property is not defined, this method will do nothing.
      * If the property is read-only, it will throw an exception.
      * @param string $name the property name    属性名
      * @throws InvalidCallException if the property is read only. 属性只读
      */
     public function __unset($name)
     {
         $setter = 'set' . $name;
         if (method_exists($this, $setter)) {
             //如果存在，由$setter设置为null
             $this->$setter(null);
         } elseif (method_exists($this, 'get' . $name)) {
             //如果是只读的，抛出异常
             throw new InvalidCallException('Unsetting read-only property: ' . get_class($this) . '::' . $name);
         }
     }

     /**
      * Calls the named method which is not a class method.
      * 调用指定的方法而不是一个类方法.
      * Do not call this method directly as it is a PHP magic method that
      * will be implicitly called when an unknown method is being invoked.
      * @param string $name the method name  方法名
      * @param array $params method parameters 方法参数
      * @throws UnknownMethodException when calling unknown method 调用未知方法
      * @return mixed the method return value
      */
     public function __call($name, $params)
     {
         //调用指定方法
         throw new UnknownMethodException('Calling unknown method: ' . get_class($this) . "::$name()");
     }

     /**
      * Returns a value indicating whether a property is defined.
      * A property is defined if:
      *
      * - the class has a getter or setter method associated with the specified name
      *   (in this case, property name is case-insensitive);
      * - the class has a member variable with the specified name (when `$checkVars` is true);
      * 检查查对象或类是否具有 $name 属性，如果 $checkVars 为 true，则不局限于是否有 getter或setter
      * @param string $name the property name    属性名
      * @param boolean $checkVars whether to treat member variables as properties 是否将成员变量作为属性对待 true/false
      * @return boolean whether the property is defined  属性是否定义
      * @see canGetProperty()
      * @see canSetProperty()
      */
     public function hasProperty($name, $checkVars = true)
     {
         return $this->canGetProperty($name, $checkVars) || $this->canSetProperty($name, false);
     }

     /**
      * Returns a value indicating whether a property can be read.
      * 返回一个值指示是否可以读取属性.
      * A property is readable if:
      *
      * - the class has a getter method associated with the specified name
      *   (in this case, property name is case-insensitive);
      * - the class has a member variable with the specified name (when `$checkVars` is true);
      * 检查对象或类是否能够获取 $name 属性，如果 $checkVars 为 true，则不局限于是否有 getter
      * @param string $name the property name
      * @param boolean $checkVars whether to treat member variables as properties
      * @return boolean whether the property can be read
      * @see canSetProperty()
      */
     public function canGetProperty($name, $checkVars = true)
     {
         //是否存在该属性
         return method_exists($this, 'get' . $name) || $checkVars && property_exists($this, $name);
     }

     /**
      * Returns a value indicating whether a property can be set.
      * 属性是否可设置
      * A property is writable if:
      *
      * - the class has a setter method associated with the specified name
      *   (in this case, property name is case-insensitive);
      * - the class has a member variable with the specified name (when `$checkVars` is true);
      * 检查对象或类是否能够设置 $name 属性，如果 $checkVars 为 true，则不局限于是否有 setter
      *
      * @param string $name the property name
      * @param boolean $checkVars whether to treat member variables as properties    是否将成员变量作为属性来对待
      * @return boolean whether the property can be written  是否可写
      * @see canGetProperty()
      */
     public function canSetProperty($name, $checkVars = true)
     {
         return method_exists($this, 'set' . $name) || $checkVars && property_exists($this, $name);
     }

     /**
      * Returns a value indicating whether a method is defined.
      * 方法是否定义
      * The default implementation is a call to php function `method_exists()`.
      * You may override this method when you implemented the php magic method `__call()`.
      * @param string $name the method name
      * @return boolean whether the method is defined    是否具有 $name 方法
      */
     public function hasMethod($name)
     {
         return method_exists($this, $name);
     }
 }