yiiaseObject代码详解
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 yiiase; 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 }