Yii源码阅读笔记（五）

  1 namespace yii\base;
  2 
  3 use Yii;
  4 
  5 /**
  6  * Object is the base class that implements the *property* feature.
  7  * Object是一个基础类，实现了属性的功能
  8  * A property is defined by a getter method (e.g. `getLabel`), and/or a setter method (e.g. `setLabel`). For example,
  9  * the following getter and setter methods define a property named `label`:
 10  * 属性通过getter和setter方法定义，如下面的例子
 11  * ```php
 12  * private $_label; 定义私有的成员
 13  *
 14  * public function getLabel()
 15  * {
 16  *     return $this->_label; 通过getter方法取得_label的值
 17  * }
 18  *
 19  * public function setLabel($value)
 20  * {
 21  *     $this->_label = $value; 通过setter方法设置_label的值
 22  * }
 23  * ```
 24  *
 25  * Property names are *case-insensitive*.
 26  * 属性名是不区分大小写的
 27  * A property can be accessed like a member variable of an object. Reading or writing a property will cause the invocation
 28  * of the corresponding getter or setter method. For example,
 29  * 属性能够像一个成员变量一样被访问，读、写将会调用对应的getter或者setter方法
 30  * ```php
 31  * // equivalent to $label = $object->getLabel();
 32  * $label = $object->label;
 33  * // equivalent to $object->setLabel(‘abc‘);
 34  * $object->label = ‘abc‘;
 35  * ```
 36  *
 37  * If a property has only a getter method and has no setter method, it is considered as *read-only*. In this case, trying
 38  * to modify the property value will cause an exception.
 39  * 如果一个属性只有getter方法，那么这个属性是只读的，如果试图修改这个属性的值，将会抛出异常
 40  * 能够调用 [[hasProperty()]], [[canGetProperty()]] and/or [[canSetProperty()]] 检查一个属性
 41  *
 42  * @author Qiang Xue <qiang.xue@gmail.com>
 43  * @since 2.0
 44  */
 45 class Object implements Configurable
 46 {
 47 
 48     /**
 49      * Returns the fully qualified name of this class.
 50      * 获取静态方法调用的类名。返回类的名称，如果不是在类中调用则返回 FALSE。
 51      * @return string the fully qualified name of this class.
 52      */
 53     public static function className()
 54     {
 55         return get_called_class(); // get_called_class -- 后期静态绑定（"Late Static Binding"）类的名称
 56         // 就是用那个类调用的这个方法，就返回那个类，返回值中带有 namespace
 57     }
 58 
 59     /**
 60      * Constructor.
 61      * The default implementation does two things:
 62      * 构造方法实现了接口Configurable，通过传入的配置初始化对象，调用init（）方法
 63      * - Initializes the object with the given configuration `$config`.
 64      * - Call [[init()]].
 65      *
 66      * If this method is overridden in a child class, it is recommended that
 67      * 如果构造函数在子类中重写，必须调用父类的方法，且最后一个参数为配置数组
 68      * - the last parameter of the constructor is a configuration array, like `$config` here.
 69      * - call the parent implementation at the end of the constructor.
 70      *
 71      * @param array $config name-value pairs that will be used to initialize the object properties
 72      */
 73     public function __construct($config = [])
 74     {
 75         // 根据 $config 内容初始化该对象
 76         if (!empty($config)) {
 77             Yii::configure($this, $config);
 78         }
 79         // 调用 init() 方法，继承该类的类可以重写 init 方法，用于初始化
 80         $this->init();
 81     }
 82 
 83     /**
 84      * Initializes the object.
 85      * 初始化对象
 86      * This method is invoked at the end of the constructor after the object is initialized with the
 87      * given configuration.
 88      * 在构造函数的末尾调用，可以重写 init 方法，用于初始化
 89      */
 90     public function init()
 91     {
 92         
 93     }
 94 
 95     /**
 96      * Returns the value of an object property.
 97      * 返回对象的属性值
 98      * Do not call this method directly as it is a PHP magic method that
 99      * will be implicitly called when executing `$value = $object->property;`.
100      * 
101      * 魔术方法，实现 getter，在访问不存在的属性时调用，即成员变量设置为public时，不会被调用
102      * 
103      * @param string $name the property name
104      * @return mixed the property value
105      * @throws UnknownPropertyException if the property is not defined
106      * @throws InvalidCallException if the property is write-only
107      * @see __set()
108      */
109     public function __get($name)
110     {
111         $getter = ‘get‘ . $name; //构造getter方法
112         if (method_exists($this, $getter)) {
113             // 对象存在 $getter 方法，就直接调用
114             return $this->$getter();
115         } elseif (method_exists($this, ‘set‘ . $name)) {
116             // 如果存在 ‘set‘ . $name 方法，就认为该属性是只写的，抛出异常
117             throw new InvalidCallException(‘Getting write-only property: ‘ . get_class($this) . ‘::‘ . $name);
118         } else {
119             // 否则认为该属性不存在，抛出异常
120             throw new UnknownPropertyException(‘Getting unknown property: ‘ . get_class($this) . ‘::‘ . $name);
121         }
122     }
123 
124     /**
125      * Sets value of an object property.
126      * 设置对象的属性值
127      * Do not call this method directly as it is a PHP magic method that
128      * will be implicitly called when executing `$object->property = $value;`.
129      * 
130      * 魔术方法，实现 setter，在访问不存在的属性时调用，即成员变量设置为public时，不会被调用
131      * 
132      * @param string $name the property name or the event name
133      * @param mixed $value the property value
134      * @throws UnknownPropertyException if the property is not defined
135      * @throws InvalidCallException if the property is read-only
136      * @see __get()
137      */
138     public function __set($name, $value)
139     {
140         $setter = ‘set‘ . $name; //构造setter方法
141         if (method_exists($this, $setter)) {
142             // 对象存在 $setter 方法，就直接调用
143             $this->$setter($value);
144         } elseif (method_exists($this, ‘get‘ . $name)) {
145             // 如果存在 ‘get‘ . $name 方法，就认为该属性是只读的，抛出异常
146             throw new InvalidCallException(‘Setting read-only property: ‘ . get_class($this) . ‘::‘ . $name);
147         } else {
148             // 否则认为该属性不存在，，抛出异常
149             throw new UnknownPropertyException(‘Setting unknown property: ‘ . get_class($this) . ‘::‘ . $name);
150         }
151     }
152 
153     /**
154      * 检查属性是否被设置
155      * 
156      * 魔术方法，实现 isset，用isset() 判断对象不可见的属性时(protected/private/不存在的属性)被调用
157      * 基于 getter 实现，有 getter 方法的属性才算存在
158      * @param string $name the property name or the event name
159      * @return boolean whether the named property is set (not null).
160      * @see http://php.net/manual/en/function.isset.php
161      */
162     public function __isset($name)
163     {
164         $getter = ‘get‘ . $name;
165         if (method_exists($this, $getter)) {
166             // 判断是否有getter方法，且是否有返回值，有 getter 方法且获取的值不为 null，才认为该属性存在
167             return $this->$getter() !== null;
168         } else {
169             return false;
170         }
171     }
172 
173     /**
174      *
175      * 魔术方法，实现 unset，在注销不可见的属性时(protected/private/不存在的属性)时被调用
176      * 基于 setter 实现，有 setter 方法的属性才能 unset 掉
177      * @param string $name 属性名
178      * @throws InvalidCallException if the property is read only.
179      * @see http://php.net/manual/en/function.unset.php
180      */
181     public function __unset($name)
182     {
183         $setter = ‘set‘ . $name; //构造setter方法
184         if (method_exists($this, $setter)) {
185             // 如果setter方法存在，通过 setter 方法，将它设置为 null
186             $this->$setter(null);
187         } elseif (method_exists($this, ‘get‘ . $name)) {
188              // 如果存在 ‘get‘ . $name 方法，就认为该属性是只读的，抛出异常
189             throw new InvalidCallException(‘Unsetting read-only property: ‘ . get_class($this) . ‘::‘ . $name);
190         }
191     }
192 
193     /**
194      *重写了__call（）方法，在调用不存在的方法时会调用此方法，抛出异常
195      * @param string $name 方法名
196      * @param array $params 方法参数
197      * @throws UnknownMethodException when calling unknown method 异常
198      * @return mixed the method return value
199      */
200     public function __call($name, $params)
201     {
202         throw new UnknownMethodException(‘Calling unknown method: ‘ . get_class($this) . "::$name()");
203     }
204 
205     /**
206      *
207      * 检查对象或类是否具有 $name 属性，如果 $checkVars 为 true，则不局限于是否有 getter/setter
208      * 
209      * @param string $name 属性名
210      * @param boolean $checkVars 是否检查成员变量，默认为true
211      * @return boolean 属性是否被定义
212      * @see canGetProperty()
213      * @see canSetProperty()
214      */
215     public function hasProperty($name, $checkVars = true)
216     {
217         return $this->canGetProperty($name, $checkVars) || $this->canSetProperty($name, false);
218     }
219 
220     /**
221      *
222      * 检查对象或类是否能够获取 $name 属性，如果 $checkVars 为 true，则不局限于是否有 getter
223      * 
224      * @param string $name 属性名
225      * @param boolean $checkVars 是否检查成员变量，默认为true
226      * @return boolean 属性是否可读
227      * @see canSetProperty()
228      */
229     public function canGetProperty($name, $checkVars = true)
230     {
231         // property_exists — 检查对象或类是否具有该属性
232         return method_exists($this, ‘get‘ . $name) || $checkVars && property_exists($this, $name);
233     }
234 
235     /**
236      *
237      * 检查对象或类是否能够设置 $name 属性，如果 $checkVars 为 true，则不局限于是否有 setter
238      * 
239      * @param string $name 属性名
240      * @param boolean $checkVars 是否检查成员变量，默认为true
241      * @return boolean 属性是否可写
242      * @see canGetProperty()
243      */
244     public function canSetProperty($name, $checkVars = true)
245     {
246         return method_exists($this, ‘set‘ . $name) || $checkVars && property_exists($this, $name);
247     }
248 
249     /**
250      * 调用php的 `method_exists()`函数.
251      * You may override this method when you implemented the php magic method `__call()`.
252      * 
253      * 检查对象或类是否具有 $name 方法 
254      * 
255      * @param string $name 方法名
256      * @return boolean 方法是否被定义
257      */
258     public function hasMethod($name)
259     {
260         return method_exists($this, $name);
261     }
262 
263 }