组件（Component）
组件是 Yii 应用的主要基石。是 yiiaseComponent 类或其子类的实例。三个用以区分它和其它类的主要功能有：
或单独使用，或彼此配合，这些功能的应用让 Yii 的类变得更加灵活和易用。以小部件 yiijuiDatePicker 来举例，这是个方便你在 视图 中生成一个交互式日期选择器的 UI 组件：
use yiijuiDatePicker; echo DatePicker::widget([ 'language' => 'zh-CN', 'name' => 'country', 'clientOptions' => [ 'dateFormat' => 'yy-mm-dd', ], ]);
这个小部件继承自 yiiaseComponent，它的各项属性改写起来会很容易。
正是因为组件功能的强大，他们比常规的对象（Object）稍微重量级一点，因为他们要使用额外的内存和 CPU 时间来处理 事件 和 行为 。如果你不需要这两项功能，可以继承 yiiaseObject 而不是 yiiaseComponent。这样组件可以像普通 PHP 对象一样高效，同时还支持属性（Property）功能。
当继承 yiiaseComponent 或 yiiaseObject 时，推荐你使用如下的编码风格：
- 若你需要重写构造方法（Constructor），传入
$config作为构造器方法最后一个参数，然后把它传递给父类的构造方法。 - 永远在你重写的构造方法结尾处调用一下父类的构造方法。
- 如果你重写了 yiiaseObject::init() 方法，请确保你在
init方法的开头处调用了父类的init方法。
例子如下：
namespace yiicomponentsMyClass; use yiiaseObject; class MyClass extends Object { public $prop1; public $prop2; public function __construct($param1, $param2, $config = []) { // ... 配置生效前的初始化过程 parent::__construct($config); } public function init() { parent::init(); // ... 配置生效后的初始化过程 } }
另外，为了让组件可以在创建实例时能被正确配置，请遵照以下操作流程：
$component = new MyClass(1, 2, ['prop1' => 3, 'prop2' => 4]); // 方法二： $component = Yii::createObject([ 'class' => MyClass::className(), 'prop1' => 3, 'prop2' => 4, ], [1, 2]);
yiiaseComponent代码详解
<?php /** * @link http://www.yiiframework.com/ * @copyright Copyright (c) 2008 Yii Software LLC * @license http://www.yiiframework.com/license/ */ namespace yiiase; use Yii; /** * Component is the base class that implements the *property*, *event* and *behavior* features. * * Component provides the *event* and *behavior* features, in addition to the *property* feature which is implemented in * its parent class [[Object]]. * * Event is a way to "inject" custom code into existing code at certain places. For example, a comment object can trigger * an "add" event when the user adds a comment. We can write custom code and attach it to this event so that when the event * is triggered (i.e. comment will be added), our custom code will be executed. * * An event is identified by a name that should be unique within the class it is defined at. Event names are *case-sensitive*. * * One or multiple PHP callbacks, called *event handlers*, can be attached to an event. You can call [[trigger()]] to * raise an event. When an event is raised, the event handlers will be invoked automatically in the order they were * attached. * * To attach an event handler to an event, call [[on()]]: * * ~~~ * $post->on('update', function ($event) { * // send email notification * }); * ~~~ * * In the above, an anonymous function is attached to the "update" event of the post. You may attach * the following types of event handlers: * * - anonymous function: `function ($event) { ... }` * - object method: `[$object, 'handleAdd']` * - static class method: `['Page', 'handleAdd']` * - global function: `'handleAdd'` * * The signature of an event handler should be like the following: * * ~~~ * function foo($event) * ~~~ * * where `$event` is an [[Event]] object which includes parameters associated with the event. * * You can also attach a handler to an event when configuring a component with a configuration array. * The syntax is like the following: * * ~~~ * [ * 'on add' => function ($event) { ... } * ] * ~~~ * * where `on add` stands for attaching an event to the `add` event. * * Sometimes, you may want to associate extra data with an event handler when you attach it to an event * and then access it when the handler is invoked. You may do so by * * ~~~ * $post->on('update', function ($event) { * // the data can be accessed via $event->data * }, $data); * ~~~ * * A behavior is an instance of [[Behavior]] or its child class. A component can be attached with one or multiple * behaviors. When a behavior is attached to a component, its public properties and methods can be accessed via the * component directly, as if the component owns those properties and methods. * * To attach a behavior to a component, declare it in [[behaviors()]], or explicitly call [[attachBehavior]]. Behaviors * declared in [[behaviors()]] are automatically attached to the corresponding component. * * One can also attach a behavior to a component when configuring it with a configuration array. The syntax is like the * following: * * ~~~ * [ * 'as tree' => [ * 'class' => 'Tree', * ], * ] * ~~~ * * where `as tree` stands for attaching a behavior named `tree`, and the array will be passed to [[Yii::createObject()]] * to create the behavior object. * * @property Behavior[] $behaviors List of behaviors attached to this component. This property is read-only. * * @author Qiang Xue <qiang.xue@gmail.com> * @since 2.0 */ class Component extends Object { /** * 用来存储该对象的 event * @var array the attached event handlers (event name => handlers) */ private $_events = []; /** * 用来存储该对象的 behavior * @var Behavior[]|null the attached behaviors (behavior name => behavior). This is `null` when not initialized. */ private $_behaviors; /** * Returns the value of a component property. * This method will check in the following order and act accordingly: * * - a property defined by a getter: return the getter result * - a property of a behavior: return the behavior property value * * Do not call this method directly as it is a PHP magic method that * will be implicitly called when executing `$value = $component->property;`. * * 重写 Object 中的 getter 方法，添加对 behaviors 的处理，循环 behaviors，如果其中有相应的方法，就执行它 * * @param string $name the property name * @return mixed the property value or the value of a behavior's property * @throws UnknownPropertyException if the property is not defined * @throws InvalidCallException if the property is write-only. * @see __set() */ public function __get($name) { $getter = 'get' . $name; if (method_exists($this, $getter)) { // read property, e.g. getName() // $getter 方法存在的话就直接调用方法 return $this->$getter(); } else { // behavior property $this->ensureBehaviors(); foreach ($this->_behaviors as $behavior) { if ($behavior->canGetProperty($name)) { // 如果 behavior 中含有该属性，就返回 behavior 中的这个属性 return $behavior->$name; } } } if (method_exists($this, 'set' . $name)) { throw new InvalidCallException('Getting write-only property: ' . get_class($this) . '::' . $name); } else { throw new UnknownPropertyException('Getting unknown property: ' . get_class($this) . '::' . $name); } } /** * Sets the value of a component property. * This method will check in the following order and act accordingly: * * - a property defined by a setter: set the property value * - an event in the format of "on xyz": attach the handler to the event "xyz" * - a behavior in the format of "as xyz": attach the behavior named as "xyz" * - a property of a behavior: set the behavior property value * * Do not call this method directly as it is a PHP magic method that * will be implicitly called when executing `$component->property = $value;`. * * 重写 Object 中的 setter 方法 * 如果 $name 是 'on xyz'，就会将 xyz 事件添加到该对象中 * 如果 $name 是 'as xyz'，就会将 xyz 行为添加到该对象中 * 添加对 behaviors 的处理，循环 behaviors，如果其中有相应的属性，就设置它 * * @param string $name the property name or the event name * @param mixed $value the property value * @throws UnknownPropertyException if the property is not defined * @throws InvalidCallException if the property is read-only. * @see __get() */ public function __set($name, $value) { $setter = 'set' . $name; if (method_exists($this, $setter)) { // set property // 存在 $setter 方法，其优先级最高 $this->$setter($value); return; } elseif (strncmp($name, 'on ', 3) === 0) { // 如果 $name 是以 'on ' 开头的，就添加事件 // on event: attach event handler $this->on(trim(substr($name, 3)), $value); return; } elseif (strncmp($name, 'as ', 3) === 0) { // 如果 $name 是以 'as ' 开头的，添加行为 // as behavior: attach behavior $name = trim(substr($name, 3)); // $value 是一个 behavior 的实例或者 behavior 的配置 $this->attachBehavior($name, $value instanceof Behavior ? $value : Yii::createObject($value)); return; } else { // behavior property $this->ensureBehaviors(); // 循环所有的 behavior foreach ($this->_behaviors as $behavior) { if ($behavior->canSetProperty($name)) { // 如果 behavior 中有 $name 属性，就将 $value 赋给它 $behavior->$name = $value; return; } } } if (method_exists($this, 'get' . $name)) { throw new InvalidCallException('Setting read-only property: ' . get_class($this) . '::' . $name); } else { throw new UnknownPropertyException('Setting unknown property: ' . get_class($this) . '::' . $name); } } /** * Checks if a property value is null. * This method will check in the following order and act accordingly: * * - a property defined by a setter: return whether the property value is null * - a property of a behavior: return whether the property value is null * * Do not call this method directly as it is a PHP magic method that * will be implicitly called when executing `isset($component->property)`. * * 重写 Object 中的 isset 方法，添加对 behaviors 的处理，循环 behaviors，如果其中有相应的属性，就认为有 * * @param string $name the property name or the event name * @return boolean whether the named property is null */ public function __isset($name) { $getter = 'get' . $name; if (method_exists($this, $getter)) { // 如果 $getter 方法存在，且不为 null，就返回 true return $this->$getter() !== null; } else { // behavior property $this->ensureBehaviors(); // 循环所有的 behavior foreach ($this->_behaviors as $behavior) { if ($behavior->canGetProperty($name)) { // 如果 behavior 中有 $name 属性，且不为 null，就返回 true return $behavior->$name !== null; } } } return false; } /** * Sets a component property to be null. * This method will check in the following order and act accordingly: * * - a property defined by a setter: set the property value to be null * - a property of a behavior: set the property value to be null * * Do not call this method directly as it is a PHP magic method that * will be implicitly called when executing `unset($component->property)`. * * 重写 Object 中的 unset 方法，添加对 behaviors 的处理，循环 behaviors，如果其中有相应的属性，设置为空 * * @param string $name the property name * @throws InvalidCallException if the property is read only. */ public function __unset($name) { $setter = 'set' . $name; if (method_exists($this, $setter)) { // 如果 $setter 方法存在，且不为 null，就返回 true $this->$setter(null); return; } else { // behavior property $this->ensureBehaviors(); // 循环所有的 behavior foreach ($this->_behaviors as $behavior) { if ($behavior->canSetProperty($name)) { // 如果 behavior 中有 $name 属性，就将该属性设为 null $behavior->$name = null; return; } } } throw new InvalidCallException('Unsetting an unknown or read-only property: ' . get_class($this) . '::' . $name); } /** * Calls the named method which is not a class method. * * This method will check if any attached behavior has * the named method and will execute it if available. * * Do not call this method directly as it is a PHP magic method that * will be implicitly called when an unknown method is being invoked. * * 重写 Object 中的 call 方法，添加对 behaviors 的处理，循环 behaviors，如果其中有相应方法，就执行该 behavior 的方法 * * @param string $name the method name * @param array $params method parameters * @return mixed the method return value * @throws UnknownMethodException when calling unknown method */ public function __call($name, $params) { $this->ensureBehaviors(); foreach ($this->_behaviors as $object) { if ($object->hasMethod($name)) { // behavior 中存在名为 $name 的方法，就执行它 // call_user_func_array — 调用回调函数，并把一个数组参数作为回调函数的参数 return call_user_func_array([$object, $name], $params); } } throw new UnknownMethodException('Calling unknown method: ' . get_class($this) . "::$name()"); } /** * This method is called after the object is created by cloning an existing one. * It removes all behaviors because they are attached to the old object. * * 执行 clone 时，将其 _events 和 _behaviors 设置为空 * 对象复制可以通过 clone 关键字来完成（如果可能，这将调用对象的 __clone() 方法）。对象中的 __clone() 方法不能被直接调用。 * ~~~ * $copy_of_object = clone $object; * ~~~ * 当对象被复制后，PHP 5 会对对象的所有属性执行一个浅复制（shallow copy）。所有的引用属性 仍然会是一个指向原来的变量的引用。 */ public function __clone() { // 对象复制时，将它的 _events 设置为空数组，将 _behaviors 设置为 null $this->_events = []; $this->_behaviors = null; } /** * Returns a value indicating whether a property is defined for this component. * A property is defined if: * * - the class has a getter or setter method associated with the specified name * (in this case, property name is case-insensitive); * - the class has a member variable with the specified name (when `$checkVars` is true); * - an attached behavior has a property of the given name (when `$checkBehaviors` is true). * * 与 Object 中的方法类似，只是添加了是否检测 behavior 的参数 * * @param string $name the property name * @param boolean $checkVars whether to treat member variables as properties * @param boolean $checkBehaviors whether to treat behaviors' properties as properties of this component * @return boolean whether the property is defined * @see canGetProperty() * @see canSetProperty() */ public function hasProperty($name, $checkVars = true, $checkBehaviors = true) { // $checkVars 标记是否 check 对象的是否具有该属性（不是 getter 和 setter 定义出的属性） // $checkBehaviors 标记是否 check behavior 中的属性 return $this->canGetProperty($name, $checkVars, $checkBehaviors) || $this->canSetProperty($name, false, $checkBehaviors); } /** * Returns a value indicating whether a property can be read. * A property can be read if: * * - the class has a getter method associated with the specified name * (in this case, property name is case-insensitive); * - the class has a member variable with the specified name (when `$checkVars` is true); * - an attached behavior has a readable property of the given name (when `$checkBehaviors` is true). * * 检查对象或类是否能够获取 $name 属性 * * @param string $name the property name * @param boolean $checkVars whether to treat member variables as properties * @param boolean $checkBehaviors whether to treat behaviors' properties as properties of this component * @return boolean whether the property can be read * @see canSetProperty() */ public function canGetProperty($name, $checkVars = true, $checkBehaviors = true) { if (method_exists($this, 'get' . $name) || $checkVars && property_exists($this, $name)) { return true; } elseif ($checkBehaviors) { $this->ensureBehaviors(); foreach ($this->_behaviors as $behavior) { if ($behavior->canGetProperty($name, $checkVars)) { // behavior 中存在名为 $name 的可读属性，就认为该对象也存在 return true; } } } return false; } /** * Returns a value indicating whether a property can be set. * A property can be written if: * * - the class has a setter method associated with the specified name * (in this case, property name is case-insensitive); * - the class has a member variable with the specified name (when `$checkVars` is true); * - an attached behavior has a writable property of the given name (when `$checkBehaviors` is true). * * 检查对象或类是否能够设置 $name 属性 * * @param string $name the property name * @param boolean $checkVars whether to treat member variables as properties * @param boolean $checkBehaviors whether to treat behaviors' properties as properties of this component * @return boolean whether the property can be written * @see canGetProperty() */ public function canSetProperty($name, $checkVars = true, $checkBehaviors = true) { if (method_exists($this, 'set' . $name) || $checkVars && property_exists($this, $name)) { return true; } elseif ($checkBehaviors) { $this->ensureBehaviors(); foreach ($this->_behaviors as $behavior) { if ($behavior->canSetProperty($name, $checkVars)) { // behavior 中存在名为 $name 的可写属性，就认为该对象也存在 return true; } } } return false; } /** * Returns a value indicating whether a method is defined. * A method is defined if: * * - the class has a method with the specified name * - an attached behavior has a method with the given name (when `$checkBehaviors` is true). * * 检查对象或类是否具有 $name 方法, $checkBehaviors 标记是否 check behavior 中的方法 * * @param string $name the property name * @param boolean $checkBehaviors whether to treat behaviors' methods as methods of this component * @return boolean whether the property is defined */ public function hasMethod($name, $checkBehaviors = true) { if (method_exists($this, $name)) { return true; } elseif ($checkBehaviors) { $this->ensureBehaviors(); foreach ($this->_behaviors as $behavior) { if ($behavior->hasMethod($name)) { // behavior 中存在名为 $name 的方法，就认为该对象也存在 return true; } } } return false; } /** * Returns a list of behaviors that this component should behave as. * * Child classes may override this method to specify the behaviors they want to behave as. * * The return value of this method should be an array of behavior objects or configurations * indexed by behavior names. A behavior configuration can be either a string specifying * the behavior class or an array of the following structure: * * ~~~ * 'behaviorName' => [ * 'class' => 'BehaviorClass', * 'property1' => 'value1', * 'property2' => 'value2', * ] * ~~~ * * Note that a behavior class must extend from [[Behavior]]. Behavior names can be strings * or integers. If the former, they uniquely identify the behaviors. If the latter, the corresponding * behaviors are anonymous and their properties and methods will NOT be made available via the component * (however, the behaviors can still respond to the component's events). * * Behaviors declared in this method will be attached to the component automatically (on demand). * * 定义该对象中要用到的 behavior，格式如上 * * @return array the behavior configurations. */ public function behaviors() { return []; } /** * Returns a value indicating whether there is any handler attached to the named event. * * 判断 _events 中的一个 event 是否具有 handler * @param string $name the event name * @return boolean whether there is any handler attached to the event. */ public function hasEventHandlers($name) { $this->ensureBehaviors(); // _events 中存在 $name 的 event 或者 $name 的 event 是否含有该对象所在的类的 handler return !empty($this->_events[$name]) || Event::hasHandlers($this, $name); } /** * Attaches an event handler to an event. * * The event handler must be a valid PHP callback. The followings are * some examples: * * ~~~ * function ($event) { ... } // anonymous function * [$object, 'handleClick'] // $object->handleClick() * ['Page', 'handleClick'] // Page::handleClick() * 'handleClick' // global function handleClick() * ~~~ * * The event handler must be defined with the following signature, * * ~~~ * function ($event) * ~~~ * * where `$event` is an [[Event]] object which includes parameters associated with the event. * * @param string $name the event name * @param callable $handler the event handler * @param mixed $data the data to be passed to the event handler when the event is triggered. * When the event handler is invoked, this data can be accessed via [[Event::data]]. * @param boolean $append whether to append new event handler to the end of the existing * handler list. If false, the new handler will be inserted at the beginning of the existing * handler list. * @see off() */ public function on($name, $handler, $data = null, $append = true) { // 保证 behaviors 都加载进来了 $this->ensureBehaviors(); // $append表示是否就加到 event 的后面 if ($append || empty($this->_events[$name])) { $this->_events[$name][] = [$handler, $data]; } else { // 加到 event 的前面 array_unshift($this->_events[$name], [$handler, $data]); } } /** * Detaches an existing event handler from this component. * This method is the opposite of [[on()]]. * @param string $name event name * @param callable $handler the event handler to be removed. * If it is null, all handlers attached to the named event will be removed. * @return boolean if a handler is found and detached * @see on() */ public function off($name, $handler = null) { // 保证 behaviors 都加载进来了 $this->ensureBehaviors(); // 相应的事件不存在，就返回false if (empty($this->_events[$name])) { return false; } // 没有handler，就意味着要全部去掉 if ($handler === null) { unset($this->_events[$name]); return true; } else { $removed = false; foreach ($this->_events[$name] as $i => $event) { // $event[0]是handler，$event[1]是数据 if ($event[0] === $handler) { unset($this->_events[$name][$i]); $removed = true; } } if ($removed) { // 如果有移出事件的handler，就需要重新构建以下索引，否则会出现index为1,3,4的情况 $this->_events[$name] = array_values($this->_events[$name]); } return $removed; } } /** * Triggers an event. * This method represents the happening of an event. It invokes * all attached handlers for the event including class-level handlers. * @param string $name the event name * @param Event $event the event parameter. If not set, a default [[Event]] object will be created. */ public function trigger($name, Event $event = null) { // 保证 behaviors 都加载进来了 $this->ensureBehaviors(); if (!empty($this->_events[$name])) { // 构建Event对象，为传入到handler函数中做准备 if ($event === null) { $event = new Event; } if ($event->sender === null) { $event->sender = $this; } $event->handled = false; $event->name = $name; foreach ($this->_events[$name] as $handler) { // 给event的data属性赋值 $event->data = $handler[1]; // handler的函数中传入了一个Event对象 call_user_func($handler[0], $event); // stop further handling if the event is handled // 事件是否被handle，当handled被设置为true时，执行到这个event的时候，会停止，并忽略剩下的event if ($event->handled) { return; } } } // invoke class-level attached handlers // 触发class级别的handler Event::trigger($this, $name, $event); }