PageRenderTime 36ms CodeModel.GetById 26ms app.highlight 6ms RepoModel.GetById 2ms app.codeStats 0ms

/framework/base/Object.php

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