yii2源碼學習筆記(二）

 yii\base\Object代碼詳解

  1 <?php
  2 /**
  3  * @link http://www.yiiframework.com/
  4  * @copyright Copyright (c) 2008 Yii Software LLC
  5  * @license http://www.yiiframework.com/license/
  6  */
  7 
  8 namespace yii\base;
  9 
 10 use Yii;
 11 
 12 /**
 13  * Object is the base class that implements the *property* feature.
 14  * Object 是一個實現屬性功能的基類
 15  * A property is defined by a getter method (e.g. `getLabel`), and/or a setter method (e.g. `setLabel`). For example,
 16  * 定義了getter和setter方法。例如：
 17  * the following getter and setter methods define a property named `label`:
 18  * 
 19  * ~~~
 20  * private $_label;
 21  *
 22  * public function getLabel()
 23  * {
 24  *     return $this->_label;
 25  * }
 26  *
 27  * public function setLabel($value)
 28  * {
 29  *     $this->_label = $value;
 30  * }
 31  * ~~~
 32  *
 33  * Property names are *case-insensitive*.
 34  * 屬性名大小寫敏感
 35  * A property can be accessed like a member variable of an object. Reading or writing a property will cause the invocation
 36  * of the corresponding getter or setter method. For example,
 37  * 能夠訪問對象的屬性，如對象的成員變量。讀或寫一個屬性將致使調用相應的getter或setter方法
 38  * ~~~
 39  * // equivalent to $label = $object->getLabel();
 40  * $label = $object->label;
 41  * // equivalent to $object->setLabel('abc');
 42  * $object->label = 'abc';
 43  * ~~~
 44  *
 45  * If a property has only a getter method and has no setter method, it is considered as *read-only*. In this case, trying
 46  * to modify the property value will cause an exception.
 47  * 若是一個屬性只有getter方法，就只能讀，若是寫會出現異常。
 48  * One can call [[hasProperty()]], [[canGetProperty()]] and/or [[canSetProperty()]] to check the existence of a property.
 49  * 經過hasProperty canGetProperty或canSetProperty 檢查屬性是否存在
 50  * Besides the property feature, Object also introduces an important object initialization life cycle. In particular,
 51  * creating an new instance of Object or its derived class will involve the following life cycles sequentially:
 52  * 除了屬性特徵，對象還引入了一個重要的對象初始化生命週期，
 53  * 建立一個新的對象或其派生類的實例，將涉及下列生命週期
 54  * 1. the class constructor is invoked;
 55  * 2. object properties are initialized according to the given configuration;
 56  * 3. the `init()` method is invoked.
 57  *  調用構造函數;
 58  *  根據給定的對象屬性初始化配置;
 59  *  init()調用的方法.
 60  * In the above, both Step 2 and 3 occur at the end of the class constructor. It is recommended that
 61  * you perform object initialization in the `init()` method because at that stage, the object configuration
 62  * is already applied.
 63  * 2和3發生在類構造函數的末端。建議
 64  * 你完成對象的初始化在` init（）`方法由於在那個階段，對象配置已經應用。
 65  * In order to ensure the above life cycles, if a child class of Object needs to override the constructor,
 66  * it should be done like the following:
 67  * 爲了保證的生命週期，若是一個子類的對象須要重寫構造函數，
 68  * ~~~
 69  * public function __construct($param1, $param2, ..., $config = [])
 70  * {
 71  *     ...
 72  *     parent::__construct($config);
 73  * }
 74  * ~~~
 75  *
 76  * That is, a `$config` parameter (defaults to `[]`) should be declared as the last parameter
 77  * of the constructor, and the parent implementation should be called at the end of the constructor.
 78  * 一個配置的參數應該聲明爲最後一個參數，構造函數和父類的實現應該在結尾調用
 79  * @author Qiang Xue <qiang.xue@gmail.com>
 80  * @since 2.0
 81  */
 82 class Object
 83 {
 84     /**
 85      * Returns the fully qualified name of this class. 獲取靜態方法調用的類名，返回類的名稱
 86      * @return string the fully qualified name of this class.
 87      */
 88     public static function className()
 89     {   //哪一個類調用，就返回哪一個類，
 90         return get_called_class();
 91     }
 92 
 93     /**
 94      * Constructor.
 95      * The default implementation does two things:
 96      *
 97      * - Initializes the object with the given configuration `$config`.
 98      * - Call [[init()]].
 99      *
100      * If this method is overridden in a child class, it is recommended that
101      *
102      * - the last parameter of the constructor is a configuration array, like `$config` here.
103      * - call the parent implementation at the end of the constructor.
104      *
105      * @param array $config name-value pairs that will be used to initialize the object properties
106      */
107     public function __construct($config = [])
108     {
109         //根據$config初始化對象
110         if (!empty($config)) {
111             Yii::configure($this, $config);
112         }
113         //調用 init（）方法，用於初始化，能夠被重寫。
114         $this->init();
115     }
116 
117     /**
118      * Initializes the object.
119      * This method is invoked at the end of the constructor after the object is initialized with the
120      * given configuration.
121      * 初始化結束時調用，與給定的配置初始化。
122      */
123     public function init()
124     {
125     }
126 
127     /**
128      * Returns the value of an object property.
129      *
130      * Do not call this method directly as it is a PHP magic method that
131      * will be implicitly called when executing `$value = $object->property;`.
132      * 不要直接調用這個方法,由於它是一個PHP魔術方法，要隱式調用
133      * @param string $name the property name 屬性名稱
134      * @return mixed the property value      屬性值
135      * @throws UnknownPropertyException if the property is not defined 屬性未定義
136      * @throws InvalidCallException if the property is write-only   該屬性寫
137      * @see __set()
138      */
139     public function __get($name)
140     {
141         $getter = 'get' . $name;//定義$getter
142         if (method_exists($this, $getter)) {
143             return $this->$getter();//存在方法，直接調用
144         } elseif (method_exists($this, 'set' . $name)) {
145             // 若是存在 'set' . $name 方法，就認爲屬性是隻寫
146             throw new InvalidCallException('Getting write-only property: ' . get_class($this) . '::' . $name);
147         } else {
148             // 不然認爲該屬性不存在 未定義
149             throw new UnknownPropertyException('Getting unknown property: ' . get_class($this) . '::' . $name);
150         }
151     }
152 
153     /**
154      * Sets value of an object property.
155      *
156      * Do not call this method directly as it is a PHP magic method that
157      * will be implicitly called when executing `$object->property = $value;`.
158      * @param string $name the property name or the event name 屬性或事件名稱
159      * @param mixed $value the property value   屬性值
160      * @throws UnknownPropertyException if the property is not defined 未定義屬性
161      * @throws InvalidCallException if the property is read-only    屬性只寫
162      * @see __get()
163      */
164     public function __set($name, $value)
165     {
166         $setter = 'set' . $name;
167         if (method_exists($this, $setter)) {
168             $this->$setter($value);//對象存在$setter方法，直接調用
169         } elseif (method_exists($this, 'get' . $name)) {
170              // 存在 'get' . $name 方法，就認爲該屬性是隻讀
171             throw new InvalidCallException('Setting read-only property: ' . get_class($this) . '::' . $name);
172         } else {  // 不然認爲該屬性不存在 未定義
173             throw new UnknownPropertyException('Setting unknown property: ' . get_class($this) . '::' . $name);
174         }
175     }
176 
177     /**
178      * Checks if the named property is set (not null).
179      * 檢查屬性是否設置
180      * Do not call this method directly as it is a PHP magic method that
181      * will be implicitly called when executing `isset($object->property)`.
182      *
183      * Note that if the property is not defined, false will be returned. 未定義返回false
184      * @param string $name the property name or the event name  屬性名
185      * @return boolean whether the named property is set (not null).    
186      */
187     public function __isset($name)
188     {
189         $getter = 'get' . $name;
190         if (method_exists($this, $getter)) {
191             //由$getter獲取的值不爲null，該屬性存在，返回true
192             return $this->$getter() !== null;
193         } else {
194             return false;//該屬性存在，返回false
195         }
196     }
197 
198     /**
199      * Sets an object property to null.
200      * 設置一個屬性爲空
201      * Do not call this method directly as it is a PHP magic method that
202      * will be implicitly called when executing `unset($object->property)`.
203      *
204      * Note that if the property is not defined, this method will do nothing.
205      * If the property is read-only, it will throw an exception.
206      * @param string $name the property name    屬性名
207      * @throws InvalidCallException if the property is read only. 屬性只讀
208      */
209     public function __unset($name)
210     {
211         $setter = 'set' . $name;
212         if (method_exists($this, $setter)) {
213             //若是存在，由$setter設置爲null
214             $this->$setter(null);
215         } elseif (method_exists($this, 'get' . $name)) {
216             //若是是隻讀的，拋出異常
217             throw new InvalidCallException('Unsetting read-only property: ' . get_class($this) . '::' . $name);
218         }
219     }
220 
221     /**
222      * Calls the named method which is not a class method.
223      * 調用指定的方法而不是一個類方法.
224      * Do not call this method directly as it is a PHP magic method that
225      * will be implicitly called when an unknown method is being invoked.
226      * @param string $name the method name  方法名
227      * @param array $params method parameters 方法參數
228      * @throws UnknownMethodException when calling unknown method 調用未知方法
229      * @return mixed the method return value    
230      */
231     public function __call($name, $params)
232     {
233         //調用指定方法
234         throw new UnknownMethodException('Calling unknown method: ' . get_class($this) . "::$name()");
235     }
236 
237     /**
238      * Returns a value indicating whether a property is defined.
239      * A property is defined if:
240      *
241      * - the class has a getter or setter method associated with the specified name
242      *   (in this case, property name is case-insensitive);
243      * - the class has a member variable with the specified name (when `$checkVars` is true);
244      * 檢查查對象或類是否具備 $name 屬性，若是 $checkVars 爲 true，則不侷限因而否有 getter或setter
245      * @param string $name the property name    屬性名
246      * @param boolean $checkVars whether to treat member variables as properties 是否將成員變量做爲屬性對待 true/false
247      * @return boolean whether the property is defined  屬性是否認義
248      * @see canGetProperty()
249      * @see canSetProperty()
250      */
251     public function hasProperty($name, $checkVars = true)
252     {
253         return $this->canGetProperty($name, $checkVars) || $this->canSetProperty($name, false);
254     }
255 
256     /**
257      * Returns a value indicating whether a property can be read.
258      * 返回一個值指示是否能夠讀取屬性.
259      * A property is readable if:
260      *
261      * - the class has a getter method associated with the specified name
262      *   (in this case, property name is case-insensitive);
263      * - the class has a member variable with the specified name (when `$checkVars` is true);
264      * 檢查對象或類是否可以獲取 $name 屬性，若是 $checkVars 爲 true，則不侷限因而否有 getter
265      * @param string $name the property name
266      * @param boolean $checkVars whether to treat member variables as properties
267      * @return boolean whether the property can be read
268      * @see canSetProperty()
269      */
270     public function canGetProperty($name, $checkVars = true)
271     {
272         //是否存在該屬性
273         return method_exists($this, 'get' . $name) || $checkVars && property_exists($this, $name);
274     }
275 
276     /**
277      * Returns a value indicating whether a property can be set.
278      * 屬性是否可設置
279      * A property is writable if:
280      *
281      * - the class has a setter method associated with the specified name
282      *   (in this case, property name is case-insensitive);
283      * - the class has a member variable with the specified name (when `$checkVars` is true);
284      * 檢查對象或類是否可以設置 $name 屬性，若是 $checkVars 爲 true，則不侷限因而否有 setter
285      *
286      * @param string $name the property name
287      * @param boolean $checkVars whether to treat member variables as properties    是否將成員變量做爲屬性來對待
288      * @return boolean whether the property can be written  是否可寫
289      * @see canGetProperty()
290      */
291     public function canSetProperty($name, $checkVars = true)
292     {
293         return method_exists($this, 'set' . $name) || $checkVars && property_exists($this, $name);
294     }
295 
296     /**
297      * Returns a value indicating whether a method is defined.
298      * 方法是否認義
299      * The default implementation is a call to php function `method_exists()`.
300      * You may override this method when you implemented the php magic method `__call()`.
301      * @param string $name the method name
302      * @return boolean whether the method is defined    是否具備 $name 方法
303      */
304     public function hasMethod($name)
305     {
306         return method_exists($this, $name);
307     }
308 }