Yii源码阅读笔记（七）

接上次的组件（component）代码：

 /**
      * Returns a list of behaviors that this component should behave as.
      * 定义该对象中要用到的 behavior，返回一个行为列表
      * Child classes may override this method to specify the behaviors they want to behave as.
      *
      * 行为配置数组格式如下：
      *
      * ```php
      * 'behaviorName' => [
      *     'class' => 'BehaviorClass',
      *     'property1' => 'value1',
      *     'property2' => 'value2',
      * ]
      * ```
      * Behaviors declared in this method will be attached to the component automatically (on demand).
      * 定义该对象中要用到的 behavior
      * @return array 行为配置.
      */
     public function behaviors()
     {
         return [];
     }

     /**
      * Returns a value indicating whether there is any handler attached to the named event.
      * 判断 _events 中的一个 event 是否具有事件处理程序
      * @param string $name 事件名
      * @return boolean whether there is any handler attached to the event.
      */
     public function hasEventHandlers($name)
     {
         $this->ensureBehaviors();
         //短路写法，判断调用_events中是否有$name事件，没有直接返回false，否则，调用Event类中的的方法判断是否有处理程序
         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 following are
      * some examples:
      * 事件处理程序必须是有效的PHP回调函数，方便内置方法call_user_fucn()调用 ，例如：
      * ```
      * function ($event) { ... }         // 匿名函数
      * [$object, 'handleClick']          // 以数组形式表示的对象的方法
      * ['Page', 'handleClick']           // 静态方法
      * '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.
      * `$event`是一个包含于event相关联的[[Event]]对象
      * @param string $name 事件名
      * @param callable $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)
     {
         $this->ensureBehaviors();//确保所有的行为都加载到组件中
         if ($append || empty($this->_events[$name])) {//$append 判断是否添加到事件（event）的后面，且确保_events中有该事件
             $this->_events[$name][] = [$handler, $data];//将事件处理程序和参数添加到event数组中
         } else {//否则，添加到event数组的前面
             array_unshift($this->_events[$name], [$handler, $data]);
         }
     }

     /**
      * Detaches an existing event handler from this component.
      * This method is the opposite of [[on()]].
      *
      * [[on()]]方法的反方法，用于删除事件处理程序
      *
      * @param string $name 事件名
      * @param callable $handler 事件处理程序
      * 如果$handler 为空，清除该事件的所有时间处理程序
      * @return boolean if a handler is found and detached
      * @see on()
      */
     public function off($name, $handler = null)
     {
         $this->ensureBehaviors();//确保所有的行为都加载到组件中
         if (empty($this->_events[$name])) {//如果_events中没有该事件，也就是事件不存在
             return false;                 //返回false
         }
         if ($handler === null) {//如果事件处理程序为空
             unset($this->_events[$name]);//清除该事件的所有事件处理程序
             return true; //返回true
         } else {
             $removed = false; //删除标记
              //否则遍历该事件 根据on（）方法的格式可以知道，$event[0]是事件处理程序，$event[1]是数据
             foreach ($this->_events[$name] as $i => $event) {
                 if ($event[0] === $handler) {//判断事件处理程序是否符合
                     unset($this->_events[$name][$i]);//删除该事件处理程序
                     $removed = true;
                 }
             }
             if ($removed) {//判断是否删除成功
                 //如果删除成功，调用array_values方法重新赋值，格式化索引
                 $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 事件名
      * @param Event $event  事件参数. 如果未设置，一个默认的 [[Event]] 对象将被创建.
      */
     public function trigger($name, Event $event = null)
     {
         $this->ensureBehaviors();
         if (!empty($this->_events[$name])) {
             if ($event === null) {
                // 构建Event对象，为传入到handler函数中做准备
                 $event = new Event;
             }
             if ($event->sender === null) {
                 $event->sender = $this;
             }
             $event->handled = false;
             $event->name = $name;
             foreach ($this->_events[$name] as $handler) {
                 //遍历_events取得处理程序名和数据
                 $event->data = $handler[1];//给[[Event]] 的data属性赋值
                 call_user_func($handler[0], $event);//通过内置函数call_user_func()调用事件处理函数，$event作为参数
                 // stop further handling if the event is handled
                 // 事件是否被handle，当handled被设置为true时，执行到这个event的时候，会停止，并忽略剩下的event--不太明白，以后追加吧
                 if ($event->handled) {
                     return;
                 }
             }
         }
         // invoke class-level attached handlers
         //[[Event]] 的静态方法，触发类级别的事件处理程序
         Event::trigger($this, $name, $event);
     }

     /**
      * Returns the named behavior object.
      * 获取行为类
      * @param string $name the behavior name
      * @return null|Behavior the behavior object, or null if the behavior does not exist
      */
     public function getBehavior($name)
     {
         $this->ensureBehaviors();
         return isset($this->_behaviors[$name]) ? $this->_behaviors[$name] : null;//_behaviors中的行为类存在，返回行为类名，否则返回空
     }

     /**
      * Returns all behaviors attached to this component.
      *
      * 获取所有的行为类
      * @return Behavior[] list of behaviors attached to this component
      */
     public function getBehaviors()
     {
         $this->ensureBehaviors();
         return $this->_behaviors;//直接返回了_behaviors
     }

     /**
      * Attaches a behavior to this component.
      * 添加一个行为到组件
      * 通过提供的配置文件创建一个Behavior对象，通过调用 [[Behavior::attach()]] 方法添加行为到组件.
      * @param string $name the name of the behavior.
      * @param string|array|Behavior $behavior 行为配置，可选项如下:
      *
      *  - 一个行为类
      *  - 一个字符串形式的指定行为类
      *  - 一个配置文件数组，通过调用[[Yii::createObject()]] 创建一个行为对象.
      *
      * @return Behavior the behavior object
      * @see detachBehavior()
      */
     public function attachBehavior($name, $behavior)
     {
         $this->ensureBehaviors();
         return $this->attachBehaviorInternal($name, $behavior);
     }

     /**
      * Attaches a list of behaviors to the component.
      * 添加行为到组件
      * 行为类通过行为名索引，且必须是一个 [[Behavior]] 对象指定的行为类或者一个配置数组
      *
      * @param array $behaviors list of behaviors to be attached to the component
      * @see attachBehavior()
      */
     public function attachBehaviors($behaviors)
     {
         $this->ensureBehaviors();
         foreach ($behaviors as $name => $behavior) {
             $this->attachBehaviorInternal($name, $behavior);
         }
     }

     /**
      * Detaches a behavior from the component.
      * 从组件解除行为
      * The behavior's [[Behavior::detach()]] method will be invoked.
      * 实现方式是调用Behavior类中的detach（）方法
      * @param string $name the behavior's name.
      * @return null|Behavior the detached behavior. Null if the behavior does not exist.
      */
     public function detachBehavior($name)
     {
         $this->ensureBehaviors();
         if (isset($this->_behaviors[$name])) {
             $behavior = $this->_behaviors[$name];
             unset($this->_behaviors[$name]);
             $behavior->detach();
             return $behavior;
         } else {
             return null;
         }
     }

     /**
      * Detaches all behaviors from the component.
      * 解除所有的行为
      */
     public function detachBehaviors()
     {
         $this->ensureBehaviors();
         foreach ($this->_behaviors as $name => $behavior) {
             $this->detachBehavior($name);
         }
     }

     /**
      * Makes sure that the behaviors declared in [[behaviors()]] are attached to this component.
      * 确保定义的行为都被添加到组件
      */
     public function ensureBehaviors()
     {
         if ($this->_behaviors === null) {// 如果$this->_behaviors为空
             $this->_behaviors = [];
             foreach ($this->behaviors() as $name => $behavior) {//遍历$this->behaviors()中的behaviors，并存储到$this->_behaviors数组中
                 $this->attachBehaviorInternal($name, $behavior);
             }
         }
     }

     /**
      * Attaches a behavior to this component.
      *  私有方法  添加一个行为到组件
      * @param string|integer $name 行为名. 如果是整数，说明该行为是匿名的
      * @param string|array|Behavior $behavior the behavior to be attached
      * @return Behavior the attached behavior.
      */
     private function attachBehaviorInternal($name, $behavior)
     {
         if (!($behavior instanceof Behavior)) {
             // $behavior不是Behavior对象，就认为是配置，通过它创建一个
             $behavior = Yii::createObject($behavior);
         }
         if (is_int($name)) {//行为名师整数
             $behavior->attach($this);//绑定行为到组件
             $this->_behaviors[] = $behavior;
         } else {
             if (isset($this->_behaviors[$name])) {
                 // 如果有同名的行为存在就先解绑掉
                 $this->_behaviors[$name]->detach();
             }
             $behavior->attach($this);//重新绑定行为到组件
             $this->_behaviors[$name] = $behavior;
         }
         return $behavior;
     }