BaseObject.php 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296
  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. namespace yii\base;
  8. use Yii;
  9. /**
  10. * BaseObject is the base class that implements the *property* feature.
  11. *
  12. * A property is defined by a getter method (e.g. `getLabel`), and/or a setter method (e.g. `setLabel`). For example,
  13. * the following getter and setter methods define a property named `label`:
  14. *
  15. * ```php
  16. * private $_label;
  17. *
  18. * public function getLabel()
  19. * {
  20. * return $this->_label;
  21. * }
  22. *
  23. * public function setLabel($value)
  24. * {
  25. * $this->_label = $value;
  26. * }
  27. * ```
  28. *
  29. * Property names are *case-insensitive*.
  30. *
  31. * A property can be accessed like a member variable of an object. Reading or writing a property will cause the invocation
  32. * of the corresponding getter or setter method. For example,
  33. *
  34. * ```php
  35. * // equivalent to $label = $object->getLabel();
  36. * $label = $object->label;
  37. * // equivalent to $object->setLabel('abc');
  38. * $object->label = 'abc';
  39. * ```
  40. *
  41. * If a property has only a getter method and has no setter method, it is considered as *read-only*. In this case, trying
  42. * to modify the property value will cause an exception.
  43. *
  44. * One can call [[hasProperty()]], [[canGetProperty()]] and/or [[canSetProperty()]] to check the existence of a property.
  45. *
  46. * Besides the property feature, BaseObject also introduces an important object initialization life cycle. In particular,
  47. * creating an new instance of BaseObject or its derived class will involve the following life cycles sequentially:
  48. *
  49. * 1. the class constructor is invoked;
  50. * 2. object properties are initialized according to the given configuration;
  51. * 3. the `init()` method is invoked.
  52. *
  53. * In the above, both Step 2 and 3 occur at the end of the class constructor. It is recommended that
  54. * you perform object initialization in the `init()` method because at that stage, the object configuration
  55. * is already applied.
  56. *
  57. * In order to ensure the above life cycles, if a child class of BaseObject needs to override the constructor,
  58. * it should be done like the following:
  59. *
  60. * ```php
  61. * public function __construct($param1, $param2, ..., $config = [])
  62. * {
  63. * ...
  64. * parent::__construct($config);
  65. * }
  66. * ```
  67. *
  68. * That is, a `$config` parameter (defaults to `[]`) should be declared as the last parameter
  69. * of the constructor, and the parent implementation should be called at the end of the constructor.
  70. *
  71. * @author Qiang Xue <qiang.xue@gmail.com>
  72. * @since 2.0.13
  73. */
  74. class BaseObject implements Configurable
  75. {
  76. /**
  77. * Returns the fully qualified name of this class.
  78. * @return string the fully qualified name of this class.
  79. * @deprecated since 2.0.14. On PHP >=5.5, use `::class` instead.
  80. */
  81. public static function className()
  82. {
  83. return get_called_class();
  84. }
  85. /**
  86. * Constructor.
  87. *
  88. * The default implementation does two things:
  89. *
  90. * - Initializes the object with the given configuration `$config`.
  91. * - Call [[init()]].
  92. *
  93. * If this method is overridden in a child class, it is recommended that
  94. *
  95. * - the last parameter of the constructor is a configuration array, like `$config` here.
  96. * - call the parent implementation at the end of the constructor.
  97. *
  98. * @param array $config name-value pairs that will be used to initialize the object properties
  99. */
  100. public function __construct($config = [])
  101. {
  102. if (!empty($config)) {
  103. Yii::configure($this, $config);
  104. }
  105. $this->init();
  106. }
  107. /**
  108. * Initializes the object.
  109. * This method is invoked at the end of the constructor after the object is initialized with the
  110. * given configuration.
  111. */
  112. public function init()
  113. {
  114. }
  115. /**
  116. * Returns the value of an object property.
  117. *
  118. * Do not call this method directly as it is a PHP magic method that
  119. * will be implicitly called when executing `$value = $object->property;`.
  120. * @param string $name the property name
  121. * @return mixed the property value
  122. * @throws UnknownPropertyException if the property is not defined
  123. * @throws InvalidCallException if the property is write-only
  124. * @see __set()
  125. */
  126. public function __get($name)
  127. {
  128. $getter = 'get' . $name;
  129. if (method_exists($this, $getter)) {
  130. return $this->$getter();
  131. } elseif (method_exists($this, 'set' . $name)) {
  132. throw new InvalidCallException('Getting write-only property: ' . get_class($this) . '::' . $name);
  133. }
  134. throw new UnknownPropertyException('Getting unknown property: ' . get_class($this) . '::' . $name);
  135. }
  136. /**
  137. * Sets value of an object property.
  138. *
  139. * Do not call this method directly as it is a PHP magic method that
  140. * will be implicitly called when executing `$object->property = $value;`.
  141. * @param string $name the property name or the event name
  142. * @param mixed $value the property value
  143. * @throws UnknownPropertyException if the property is not defined
  144. * @throws InvalidCallException if the property is read-only
  145. * @see __get()
  146. */
  147. public function __set($name, $value)
  148. {
  149. $setter = 'set' . $name;
  150. if (method_exists($this, $setter)) {
  151. $this->$setter($value);
  152. } elseif (method_exists($this, 'get' . $name)) {
  153. throw new InvalidCallException('Setting read-only property: ' . get_class($this) . '::' . $name);
  154. } else {
  155. throw new UnknownPropertyException('Setting unknown property: ' . get_class($this) . '::' . $name);
  156. }
  157. }
  158. /**
  159. * Checks if a property is set, i.e. defined and not null.
  160. *
  161. * Do not call this method directly as it is a PHP magic method that
  162. * will be implicitly called when executing `isset($object->property)`.
  163. *
  164. * Note that if the property is not defined, false will be returned.
  165. * @param string $name the property name or the event name
  166. * @return bool whether the named property is set (not null).
  167. * @see https://secure.php.net/manual/en/function.isset.php
  168. */
  169. public function __isset($name)
  170. {
  171. $getter = 'get' . $name;
  172. if (method_exists($this, $getter)) {
  173. return $this->$getter() !== null;
  174. }
  175. return false;
  176. }
  177. /**
  178. * Sets an object property to null.
  179. *
  180. * Do not call this method directly as it is a PHP magic method that
  181. * will be implicitly called when executing `unset($object->property)`.
  182. *
  183. * Note that if the property is not defined, this method will do nothing.
  184. * If the property is read-only, it will throw an exception.
  185. * @param string $name the property name
  186. * @throws InvalidCallException if the property is read only.
  187. * @see https://secure.php.net/manual/en/function.unset.php
  188. */
  189. public function __unset($name)
  190. {
  191. $setter = 'set' . $name;
  192. if (method_exists($this, $setter)) {
  193. $this->$setter(null);
  194. } elseif (method_exists($this, 'get' . $name)) {
  195. throw new InvalidCallException('Unsetting read-only property: ' . get_class($this) . '::' . $name);
  196. }
  197. }
  198. /**
  199. * Calls the named method which is not a class method.
  200. *
  201. * Do not call this method directly as it is a PHP magic method that
  202. * will be implicitly called when an unknown method is being invoked.
  203. * @param string $name the method name
  204. * @param array $params method parameters
  205. * @throws UnknownMethodException when calling unknown method
  206. * @return mixed the method return value
  207. */
  208. public function __call($name, $params)
  209. {
  210. throw new UnknownMethodException('Calling unknown method: ' . get_class($this) . "::$name()");
  211. }
  212. /**
  213. * Returns a value indicating whether a property is defined.
  214. *
  215. * A property is defined if:
  216. *
  217. * - the class has a getter or setter method associated with the specified name
  218. * (in this case, property name is case-insensitive);
  219. * - the class has a member variable with the specified name (when `$checkVars` is true);
  220. *
  221. * @param string $name the property name
  222. * @param bool $checkVars whether to treat member variables as properties
  223. * @return bool whether the property is defined
  224. * @see canGetProperty()
  225. * @see canSetProperty()
  226. */
  227. public function hasProperty($name, $checkVars = true)
  228. {
  229. return $this->canGetProperty($name, $checkVars) || $this->canSetProperty($name, false);
  230. }
  231. /**
  232. * Returns a value indicating whether a property can be read.
  233. *
  234. * A property is readable if:
  235. *
  236. * - the class has a getter method associated with the specified name
  237. * (in this case, property name is case-insensitive);
  238. * - the class has a member variable with the specified name (when `$checkVars` is true);
  239. *
  240. * @param string $name the property name
  241. * @param bool $checkVars whether to treat member variables as properties
  242. * @return bool whether the property can be read
  243. * @see canSetProperty()
  244. */
  245. public function canGetProperty($name, $checkVars = true)
  246. {
  247. return method_exists($this, 'get' . $name) || $checkVars && property_exists($this, $name);
  248. }
  249. /**
  250. * Returns a value indicating whether a property can be set.
  251. *
  252. * A property is writable if:
  253. *
  254. * - the class has a setter method associated with the specified name
  255. * (in this case, property name is case-insensitive);
  256. * - the class has a member variable with the specified name (when `$checkVars` is true);
  257. *
  258. * @param string $name the property name
  259. * @param bool $checkVars whether to treat member variables as properties
  260. * @return bool whether the property can be written
  261. * @see canGetProperty()
  262. */
  263. public function canSetProperty($name, $checkVars = true)
  264. {
  265. return method_exists($this, 'set' . $name) || $checkVars && property_exists($this, $name);
  266. }
  267. /**
  268. * Returns a value indicating whether a method is defined.
  269. *
  270. * The default implementation is a call to php function `method_exists()`.
  271. * You may override this method when you implemented the php magic method `__call()`.
  272. * @param string $name the method name
  273. * @return bool whether the method is defined
  274. */
  275. public function hasMethod($name)
  276. {
  277. return method_exists($this, $name);
  278. }
  279. }