In-depth analysis of the event mechanism in PHP's Yii framework, yiievent

Event
Events can "inject" custom code into specific execution points in existing code. Attach custom code to an event and the code will automatically execute when the event is triggered. For example, the messageSent event can be fired when a mailer object successfully sends a message. If you want to track successfully sent messages, you can attach the corresponding tracking code to the messageSent event.
Yii introduces a base class called yiibaseComponent to support events. If a class needs to trigger events, it should inherit yiibaseComponent or its subclasses.

Yii’s event mechanism
The event mechanism of YII is its unique feature. Proper use of the event mechanism will loosen the coupling between various components, which is conducive to group collaborative development.
When you need to use events, how to bind event processing functions to events, and how to trigger events are quite different from other languages. For example, in Javascript, you can use

$(‘#id').on("click",function() {});

Copy after login

The

method binds a processing function to the DOM element. When a specified event (such as click) occurs on the DOM element, the set function will be automatically executed.
However, PHP is a server-side scripting language, so there is no automatic triggering of events. Therefore, compared with Javascript, events in YII need to be triggered manually. Generally speaking, to implement the event mechanism of YII components, the following steps are required:

Define the event name. In fact, the level component defines a method starting with on, and the code in it is fixed, such as:

 public function onBeginRequest($event){
 $this->raiseEvent('onBeginRequest',$event);
}

Copy after login

That is, the function name and event name are consistent. The purpose of this step is to execute the processing functions bound to this event one by one. Writing this series of podcasts is a sort of finishing, so I will write it in more detail and now post the code of the raiseEvent method.

/** * Raises an event. 
  * This method represents the happening of an event. It invokes 
  * all attached handlers for the event. 
  * @param string $name the event name 
  * @param CEvent $event the event parameter 
  * @throws CException if the event is undefined or an event handler is invalid. 
*/

  public function raiseEvent($name,$event){  
       $name=strtolower($name);  
       //_e这个数组用来存所有事件信息
       if(isset($this->_e[$name]))  {   
          foreach($this->_e[$name] as $handler) {     
            if(is_string($handler)) 
              call_user_func($handler,$event);       
            elseif(is_callable($handler,true)){ 
                 if(is_array($handler)){        
                   // an array: 0 - object, 1 - method name  
                   list($object,$method)=$handler;   
                   if(is_string($object)) // static method call 
                    call_user_func($handler,$event); 
                   elseif(method_exists($object,$method))     
                     $object->$method($event);        
                   else         
                     throw new CException(Yii::t('yii','Event "{class}.{event}" is attached with an invalid handler "{handler}".',  array('{class}'=>get_class($this), '{event}'=>$name, '{handler}'=>$handler[1])));      
                  }      
                  else // PHP 5.3: anonymous function 
                     call_user_func($handler,$event);     
            }     
            else      
              throw new CException(Yii::t('yii','Event "{class}.{event}" is attached with an invalid handler "{handler}".', array('{class}'=>get_class($this), '{event}'=>$name, '{handler}'=>gettype($handler))));     
           // stop further handling if param.handled is set true 
            if(($event instanceof CEvent) && $event->handled) 
              return;   
          } 
        }  elseif(YII_DEBUG && !$this->hasEvent($name))   
          throw new CException(Yii::t('yii','Event "{class}.{event}" is not defined.',     array('{class}'=>get_class($this), '{event}'=>$name)));
 }

Copy after login

Event Handlers

An event handler is a PHP callback function that is executed when the event it is attached to is triggered. One of the following callback functions can be used:

PHP global function specified in string form, such as 'trim';
Object methods specified in array form of object name and method name, such as [$object, $method];
Static class method specified in array form of class name and method name, such as [$class, $method];
Anonymous functions, such as function ($event) { ... } .

The format of the event handler is:

function ($event) {
  // $event 是 yii\base\Event 或其子类的对象
}

Copy after login

Through the $event parameter, the event handler obtains the following information about the event:

yiibaseEvent::name: event name
yiibaseEvent::sender: the object that calls the trigger() method
yiibaseEvent::data: The data passed in when attaching the event handler, the default is empty, detailed below

Attached event handler

Call the yiibaseComponent::on() method to attach a handler to the event. Such as:

$foo = new Foo;

// 处理器是全局函数
$foo->on(Foo::EVENT_HELLO, 'function_name');

// 处理器是对象方法
$foo->on(Foo::EVENT_HELLO, [$object, 'methodName']);

// 处理器是静态类方法
$foo->on(Foo::EVENT_HELLO, ['app\components\Bar', 'methodName']);

// 处理器是匿名函数
$foo->on(Foo::EVENT_HELLO, function ($event) {
  //事件处理逻辑
});
附加事件处理器时可以提供额外数据作为 yii\base\Component::on() 方法的第三个参数。数据在事件被触发和处理器被调用时能被处理器使用。如：

// 当事件被触发时以下代码显示 "abc"
// 因为 $event->data 包括被传递到 "on" 方法的数据
$foo->on(Foo::EVENT_HELLO, function ($event) {
  echo $event->data;
}, 'abc');

Copy after login

Event handler order

One or more handlers can be attached to an event. When an event is triggered, the attached handlers will be called in the order they were attached. If a processor needs to stop subsequent processor calls, you can set the [yiibaseEvent::handled]] attribute of the $event parameter to true, as follows:

$foo->on(Foo::EVENT_HELLO, function ($event) {
  $event->handled = true;
});

Copy after login

By default, newly attached event handlers are placed at the end of the existing handler queue. Therefore, this handler will be called last when the event is fired. Inserting a new processor at the front of the processor queue will cause the processor to be called first. You can pass the fourth parameter $append as false and call the yiibaseComponent::on() method to achieve this:

$foo->on(Foo::EVENT_HELLO, function ($event) {
  // 这个处理器将被插入到处理器队列的第一位...
}, $data, false);

Copy after login

Trigger event

The event is triggered by calling the yiibaseComponent::trigger() method. This method must pass the event name and an event object to pass parameters to the event handler. Such as:

namespace app\components;

use yii\base\Component;
use yii\base\Event;

class Foo extends Component
{
  const EVENT_HELLO = 'hello';

  public function bar()
  {
    $this->trigger(self::EVENT_HELLO);
  }
}

Copy after login

When the above code calls bar(), it will trigger an event named hello.

Tip: It is recommended to use class constants to represent event names. In the above example, the constant EVENT_HELLO is used to represent hello. This has two benefits. First, it prevents typos and supports IDE auto-completion. Second, you can learn which events a class supports by simply inspecting the constant declarations.
Sometimes you want to pass some additional information to the event handler when the event is triggered. For example, the mail program needs to pass message information to the handler of the messageSent event so that the handler knows which messages were sent. To do this, you can provide an event object as the second parameter of the yiibaseComponent::trigger() method. This event object must be an instance of the yiibaseEvent class or its subclass. Such as:

namespace app\components;

use yii\base\Component;
use yii\base\Event;

class MessageEvent extends Event
{
  public $message;
}

class Mailer extends Component
{
  const EVENT_MESSAGE_SENT = 'messageSent';

  public function send($message)
  {
    // ...发送 $message 的逻辑...

    $event = new MessageEvent;
    $event->message = $message;
    $this->trigger(self::EVENT_MESSAGE_SENT, $event);
  }
}

Copy after login

When the yiibaseComponent::trigger() method is called, it will call all event handlers attached to the named event (the first parameter of the trigger method).

Remove event handler

To remove the handler from the event, call the yiibaseComponent::off() method. Such as:

// 处理器是全局函数
$foo->off(Foo::EVENT_HELLO, 'function_name');

// 处理器是对象方法
$foo->off(Foo::EVENT_HELLO, [$object, 'methodName']);

// 处理器是静态类方法
$foo->off(Foo::EVENT_HELLO, ['app\components\Bar', 'methodName']);

// 处理器是匿名函数
$foo->off(Foo::EVENT_HELLO, $anonymousFunction);

Copy after login

Note that you generally should not try to remove an anonymous function after it is attached to an event, unless you have stored it somewhere. In the above example, it is assumed that the anonymous function is stored as the variable $anonymousFunction.

移除事件的全部处理器，简单调用 yii\base\Component::off() 即可，不需要第二个参数：

$foo->off(Foo::EVENT_HELLO);

Copy after login

类级别的事件处理器

以上部分，我们叙述了在实例级别如何附加处理器到事件。有时想要一个类的所有实例而不是一个指定的实例都响应一个被触发的事件，并不是一个个附加事件处理器到每个实例，而是通过调用静态方法 yii\base\Event::on() 在类级别附加处理器。

例如，活动记录对象要在每次往数据库新增一条新记录时触发一个 yii\db\BaseActiveRecord::EVENT_AFTER_INSERT 事件。要追踪每个活动记录对象的新增记录完成情况，应如下写代码：

use Yii;
use yii\base\Event;
use yii\db\ActiveRecord;

Event::on(ActiveRecord::className(), ActiveRecord::EVENT_AFTER_INSERT, function ($event) {
  Yii::trace(get_class($event->sender) . ' is inserted');
});

Copy after login

每当 yii\db\BaseActiveRecord 或其子类的实例触发 yii\db\BaseActiveRecord::EVENT_AFTER_INSERT 事件时，这个事件处理器都会执行。在这个处理器中，可以通过 $event->sender 获取触发事件的对象。

当对象触发事件时，它首先调用实例级别的处理器，然后才会调用类级别处理器。

可调用静态方法yii\base\Event::trigger()来触发一个类级别事件。类级别事件不与特定对象相关联。因此，它只会引起类级别事件处理器的调用。如：

use yii\base\Event;

Event::on(Foo::className(), Foo::EVENT_HELLO, function ($event) {
  echo $event->sender; // 显示 "app\models\Foo"
});

Event::trigger(Foo::className(), Foo::EVENT_HELLO);

Copy after login

注意这种情况下 $event->sender 指向触发事件的类名而不是对象实例。

注意：因为类级别的处理器响应类和其子类的所有实例触发的事件，必须谨慎使用，尤其是底层的基类，如 yii\base\Object。
移除类级别的事件处理器只需调用yii\base\Event::off()，如：

// 移除 $handler
Event::off(Foo::className(), Foo::EVENT_HELLO, $handler);

// 移除 Foo::EVENT_HELLO 事件的全部处理器
Event::off(Foo::className(), Foo::EVENT_HELLO);

Copy after login

全局事件

所谓全局事件实际上是一个基于以上叙述的事件机制的戏法。它需要一个全局可访问的单例，如应用实例。

事件触发者不调用其自身的 trigger() 方法，而是调用单例的 trigger() 方法来触发全局事件。类似地，事件处理器被附加到单例的事件。如：

use Yii;
use yii\base\Event;
use app\components\Foo;

Yii::$app->on('bar', function ($event) {
  echo get_class($event->sender); // 显示 "app\components\Foo"
});

Yii::$app->trigger('bar', new Event(['sender' => new Foo]));

Copy after login

全局事件的一个好处是当附加处理器到一个对象要触发的事件时，不需要产生该对象。相反，处理器附加和事件触发都通过单例（如应用实例）完成。

然而，因为全局事件的命名空间由各方共享，应合理命名全局事件，如引入一些命名空间（例："frontend.mail.sent", "backend.mail.sent"）。

给组件对象绑定事件处理函数

$component->attachEventHandler($name, $handler);
$component->onBeginRequest = $handler ;

Copy after login

yii支持一个事件绑定多个回调函数，上述的两个方法都会在已有的事件上增加新的回调函数，而不会覆盖已有回调函数。
$handler即是一个PHP回调函数，关于回调函数的形式，本文的最后会附带说明。如CLogRouter组件的init事件中，有以下代码：

Yii::app()->attachEventHandler('onEndRequest',array($this,'processLogs'));

Copy after login

这就是给CApplication对象的onEndRequest绑定了CLogRouter::processLogs()回调函数。而CApplication组件确实存在名为onEndRequest的方法（即onEndRequest事件）,它之中的代码就是激活了相应的回调函数，即CLogRouter::processLogs()方法。所以从这里可以得出，日志的记录其实是发生在CApplication组件的正常退出时。

在需要触发事件的时候，直接激活组件的事件，即调用事件即可，如：比如CApplication组件的run方法中：

if($this->hasEventHandler('onBeginRequest'))
  $this->onBeginRequest(new CEvent($this));

Copy after login

这样即触发了事件处理函数。如果没有第一行的判断，那么在调试模式下（YII_DEBUG常量被定义为true），会抛出异常，而在非调试模式下（YII_DEBUG常量定义为false或没有定义YII_DEBUG常量），则不会产生任何异常。
回调函数的形式：

普通全局函数（内置的或用户自定义的）

call_user_func(‘print', $str);

Copy after login

类的静态方法，使用数组形式传递

call_user_func(array(‘className', ‘print'), $str );

Copy after login

对象方法，使用数组形式传递

$obj = new className();
call_user_func(array($obj, ‘print'), $str );

Copy after login

匿名方法，类似javascript的匿名函数

call_user_func(function($i){echo $i++;},4);

Copy after login

或使用以下形式：

$s = function($i) {
  echo $i++;
};
call_user_func($s,4);

Copy after login

总结

关于Yii的事件机制其实就是提供了一种用于解耦的方式，在需要调用event的地方之前，只要你提供了事件的实现并注册在之后的地方需要的时候即可调用。

您可能感兴趣的文章:

PHP的Yii框架中移除组件所绑定的行为的方法
PHP的Yii框架中行为的定义与绑定方法讲解
详解在PHP的Yii框架中使用行为Behaviors的方法
深入讲解PHP的Yii框架中的属性（Property）
PHP的Yii框架中使用数据库的配置和SQL操作实例教程
全面解读PHP的Yii框架中的日志功能
Yii使用find findAll查找出指定字段的实现方法
解析yii数据库的增删查改
Yii PHP Framework实用入门教程(详细介绍)
详解PHP的Yii框架中组件行为的属性注入和方法注入

In-depth analysis of the event mechanism in PHP's Yii framework, yiievent_PHP tutorial

In-depth analysis of the event mechanism in PHP's Yii framework, yiievent

您可能感兴趣的文章: