yii2源码学习笔记(四）

/**
     * 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 中的方法类似，只是添加了是否检测行为的参数
     * @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 参数，用来检查对象是否具有该属性 （不是 getter 和 setter 定义出的属性）
        //$checkBehaviors参数，用来设置是否检测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)) {
            // 存在 ‘get‘ . $name方法 或 存在该属性， 返回true
            return true;
        } elseif ($checkBehaviors) {
            $this->ensureBehaviors();
            foreach ($this->_behaviors as $behavior) {
                // behavior 中存在名为 $name 的可读属性，认为该对象也存在 返回true
                if ($behavior->canGetProperty($name, $checkVars)) {
                    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)) {
            // 存在 ‘set‘ . $name方法 或 存在该属性， 返回true
            return true;
        } elseif ($checkBehaviors) {
            $this->ensureBehaviors();
            foreach ($this->_behaviors as $behavior) {
                // behavior 中存在名为 $name 的可写属性，认为该对象也存在 返回true
                if ($behavior->canSetProperty($name, $checkVars)) {
                    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 方法
     * @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) {//标记是否 check behavior 中的方法
            $this->ensureBehaviors();
            foreach ($this->_behaviors as $behavior) {
                // behavior 中存在名为 $name 的方法，就认为该方法也存在
                if ($behavior->hasMethod($name)) {
                    return true;
                }
            }
        }
        return false;
    }

    /**
     * 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.
     * 可重写
     * 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).
     * 在这种方法中声明的行为将自动连接到组件
     * @return array the behavior configurations.
     */
    public function behaviors()
    {
        return [];
    }

    /**
     * Returns a value indicating whether there is any handler attached to the named event.
     *  判断 _events 中的一个事件是否具有事件处理程序
     * @param string $name the event name   事件名
     * @return boolean whether there is any handler attached to the event.
     */
    public function hasEventHandlers($name)
    {
        $this->ensureBehaviors();
        // 判断事件是否存在 $name 否则 调用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 followings are
     * 事件处理程序必须是有效的PHP回调函数，方便内置方法call_user_fucn()调用
     * 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]].
     * 当调用事件处理程序时，该数据可以通过 [[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();
        //$append 判断是否添加到事件（event）的后面，确保_events中有该事件
        if ($append || empty($this->_events[$name])) {
            //将事件处理程序和参数添加到event数组末尾
            $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()]].
     * [[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)
    {
        $this->ensureBehaviors();
        // 相应的事件不存在，返回false
        if (empty($this->_events[$name])) {
            return false;
        }
        //没有handler，清除该事件的所有事件处理程序 并返回true
        if ($handler === null) {
            unset($this->_events[$name]);
            return true;
        } else {
            $removed = false;//删除标记
            foreach ($this->_events[$name] as $i => $event) {
                if ($event[0] === $handler) {//遍历该事件 判断事件处理程序是否符合
                    unset($this->_events[$name][$i]);//删除该事件处理程序
                    $removed = true;
                }
            }
            if ($removed) {
                 // 如果删除成功，就需要重新构建以下索引，重新赋值
                $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.
     *  事件参数. 如果未设置，默认的 [[Event]] 对象将被创建.
     */
    public function trigger($name, Event $event = null)
    {
        //确保行为绑定
        $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) {
                // 遍历事件 给事件的data属性赋值
                $event->data = $handler[1];
                // handler的函数中传入了一个Event对象
                call_user_func($handler[0], $event);
                // stop further handling if the event is handled
                // 事件是否被处理，如果了处理事件即handled被设置为true时，停止进一步处理
                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 Behavior the behavior object, or null if the behavior does not exist 行为对象，如果行为不存在为null
     */
    public function getBehavior($name)
    {
        //确保行为绑定
        $this->ensureBehaviors();
        //_behaviors中的行为类存在，返回行为类名，否则返回空
        return isset($this->_behaviors[$name]) ? $this->_behaviors[$name] : null;
    }

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

    /**
     * Attaches a behavior to this component.
     * 内部使用的添加一个行为到该组件
     * This method will create the behavior object based on the given
     * configuration. After that, the behavior object will be attached to
     * this component by calling the [[Behavior::attach()]] method.
     * 通过提供的配置文件创建一个Behavior对象，通过调用 [[Behavior::attach()]] 方法添加行为到组件.
     * @param string $name the name of the behavior.    行为名
     * @param string|array|Behavior $behavior the behavior configuration. This can be one of the following:
     *  behavior配置
     *  - a [[Behavior]] object 一个[[Behavior]]类
     *  - a string specifying the behavior class    一个字符串形式的指定行为类
     *  - an object configuration array that will be passed to [[Yii::createObject()]] to create the behavior object.
     *  一个配置文件数组，通过调用[[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.   添加行为列表到组件
     * Each behavior is indexed by its name and should be a [[Behavior]] object,
     * a string specifying the behavior class, or an configuration array for creating the behavior.
     * 行为类通过行为名索引，且必须是一个 [[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 Behavior the detached behavior. Null if the behavior does not exist. 存在返回分离行为 不存在返回null
     */
    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 = [];
            foreach ($this->behaviors() as $name => $behavior) {
                //遍历$this->behaviors()中的behaviors，并添加到$this->_behaviors数组中
                $this->attachBehaviorInternal($name, $behavior);
            }
        }
    }

    /**
     * Attaches a behavior to this component.   内部使用的为该对象添加behavior的方法
     * @param string|integer $name the name of the behavior. If this is an integer, it means the behavior
     * is an anonymous one. Otherwise, the behavior is a named one and any existing behavior with the same name
     * will be detached first.  行为名. 如果是整数，说明该行为是匿名的
     * @param string|array|Behavior $behavior the behavior to be attached   添加的行为 string|array|Behavior
     * @return Behavior the attached behavior.
     */
    private function attachBehaviorInternal($name, $behavior)
    {
        if (!($behavior instanceof Behavior)) {
            // $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;
    }