In-depth learning of Yii2--Event

Let’s first look at the use of events in Yii2. The following content is taken from the Yii2 Chinese documentation. 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

Let’s first look at the use of events in Yii2. The following content is taken from the Yii2 Chinese documentation

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 triggered 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 named [[yiibaseComponent]] to support events. If a class needs to trigger events, it should inherit [[yiibaseComponent]] or its subclasses.

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 function, such as function ($event) { ... } .

The format of the event handler is:

<span style="color: #0000ff;">function</span> (<span style="color: #800080;">$event</span><span style="color: #000000;">) {
    </span><span style="color: #008000;">//</span><span style="color: #008000;"> $event 是 yii\base\Event 或其子类的对象</span>
}

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

• [[yiibaseEvent::name|event name]]: event name
• [[yiibaseEvent::sender|event sender]]: Object trigger() that calls the
method
• [[yiibaseEvent::data|custom data]]: The data passed in when attaching the event handler, the default is empty, detailed below

Attach event handler

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

<span style="color: #800080;">$foo</span> = <span style="color: #0000ff;">new</span><span style="color: #000000;"> Foo;

</span><span style="color: #008000;">//</span><span style="color: #008000;"> 处理器是全局函数</span>
<span style="color: #800080;">$foo</span>->on(Foo::EVENT_HELLO, 'function_name'<span style="color: #000000;">);

</span><span style="color: #008000;">//</span><span style="color: #008000;"> 处理器是对象方法</span>
<span style="color: #800080;">$foo</span>->on(Foo::EVENT_HELLO, [<span style="color: #800080;">$object</span>, 'methodName'<span style="color: #000000;">]);

</span><span style="color: #008000;">//</span><span style="color: #008000;"> 处理器是静态类方法</span>
<span style="color: #800080;">$foo</span>->on(Foo::EVENT_HELLO, ['app\components\Bar', 'methodName'<span style="color: #000000;">]);

</span><span style="color: #008000;">//</span><span style="color: #008000;"> 处理器是匿名函数</span>
<span style="color: #800080;">$foo</span>->on(Foo::EVENT_HELLO, <span style="color: #0000ff;">function</span> (<span style="color: #800080;">$event</span><span style="color: #000000;">) {
    </span><span style="color: #008000;">//</span><span style="color: #008000;">事件处理逻辑</span>
});

When attaching an event handler, you can provide additional data as the third parameter of the [[yiibaseComponent::on()]] method. The data is available to the handler when events are triggered and handlers are called. Such as:

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

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:

<span style="color: #800080;">$foo</span>->on(Foo::EVENT_HELLO, <span style="color: #0000ff;">function</span> (<span style="color: #800080;">$event</span><span style="color: #000000;">) {
    </span><span style="color: #800080;">$event</span>->handled = <span style="color: #0000ff;">true</span><span style="color: #000000;">;
});</span>

By default, newly attached event handlers are queued 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. :

<span style="color: #800080;">$foo</span>->on(Foo::EVENT_HELLO, <span style="color: #0000ff;">function</span> (<span style="color: #800080;">$event</span><span style="color: #000000;">) {
    </span><span style="color: #008000;">//</span><span style="color: #008000;"> 这个处理器将被插入到处理器队列的第一位...</span>
}, <span style="color: #800080;">$data</span>, <span style="color: #0000ff;">false</span>);

Trigger event

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

<span style="color: #000000;">namespace app\components;

</span><span style="color: #0000ff;">use</span><span style="color: #000000;"> yii\base\Component;
</span><span style="color: #0000ff;">use</span><span style="color: #000000;"> yii\base\Event;

</span><span style="color: #0000ff;">class</span> Foo <span style="color: #0000ff;">extends</span><span style="color: #000000;"> Component
{
    </span><span style="color: #0000ff;">const</span> EVENT_HELLO = 'hello'<span style="color: #000000;">;

    </span><span style="color: #0000ff;">public</span> <span style="color: #0000ff;">function</span><span style="color: #000000;"> bar()
    {
        </span><span style="color: #800080;">$this</span>->trigger(self::<span style="color: #000000;">EVENT_HELLO);
    }
}</span>

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 an 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 subclasses. Such as:

<span style="color: #000000;">namespace app\components;

</span><span style="color: #0000ff;">use</span><span style="color: #000000;"> yii\base\Component;
</span><span style="color: #0000ff;">use</span><span style="color: #000000;"> yii\base\Event;

</span><span style="color: #0000ff;">class</span> MessageEvent <span style="color: #0000ff;">extends</span><span style="color: #000000;"> Event
{
    </span><span style="color: #0000ff;">public</span> <span style="color: #800080;">$message</span><span style="color: #000000;">;
}

</span><span style="color: #0000ff;">class</span> Mailer <span style="color: #0000ff;">extends</span><span style="color: #000000;"> Component
{
    </span><span style="color: #0000ff;">const</span> EVENT_MESSAGE_SENT = 'messageSent'<span style="color: #000000;">;

    </span><span style="color: #0000ff;">public</span> <span style="color: #0000ff;">function</span> send(<span style="color: #800080;">$message</span><span style="color: #000000;">)
    {
        </span><span style="color: #008000;">//</span><span style="color: #008000;"> ...发送 $message 的逻辑...</span>

        <span style="color: #800080;">$event</span> = <span style="color: #0000ff;">new</span><span style="color: #000000;"> MessageEvent;
        </span><span style="color: #800080;">$event</span>->message = <span style="color: #800080;">$message</span><span style="color: #000000;">;
        </span><span style="color: #800080;">$this</span>->trigger(self::EVENT_MESSAGE_SENT, <span style="color: #800080;">$event</span><span style="color: #000000;">);
    }
}</span>

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).

移除事件处理器

从事件移除处理器，调用 [[yii\base\Component::off()]] 方法。如：

<span style="color: #008000;">//</span><span style="color: #008000;"> 处理器是全局函数</span>
<span style="color: #800080;">$foo</span>->off(Foo::EVENT_HELLO, 'function_name'<span style="color: #000000;">);

</span><span style="color: #008000;">//</span><span style="color: #008000;"> 处理器是对象方法</span>
<span style="color: #800080;">$foo</span>->off(Foo::EVENT_HELLO, [<span style="color: #800080;">$object</span>, 'methodName'<span style="color: #000000;">]);

</span><span style="color: #008000;">//</span><span style="color: #008000;"> 处理器是静态类方法</span>
<span style="color: #800080;">$foo</span>->off(Foo::EVENT_HELLO, ['app\components\Bar', 'methodName'<span style="color: #000000;">]);

</span><span style="color: #008000;">//</span><span style="color: #008000;"> 处理器是匿名函数</span>
<span style="color: #800080;">$foo</span>->off(Foo::EVENT_HELLO, <span style="color: #800080;">$anonymousFunction</span>);

注意当匿名函数附加到事件后一般不要尝试移除匿名函数，除非你在某处存储了它。以上示例中，假设匿名函数存储为变量$anonymousFunction 。

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

<span style="color: #800080;">$foo</span>->off(Foo::EVENT_HELLO);

类级别的事件处理器

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

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

<span style="color: #0000ff;">use</span><span style="color: #000000;"> Yii;
</span><span style="color: #0000ff;">use</span><span style="color: #000000;"> yii\base\Event;
</span><span style="color: #0000ff;">use</span><span style="color: #000000;"> yii\db\ActiveRecord;

Event</span>::on(ActiveRecord::className(), ActiveRecord::EVENT_AFTER_INSERT, <span style="color: #0000ff;">function</span> (<span style="color: #800080;">$event</span><span style="color: #000000;">) {
    Yii</span>::trace(<span style="color: #008080;">get_class</span>(<span style="color: #800080;">$event</span>->sender) . ' is inserted'<span style="color: #000000;">);
});</span>

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

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

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

<span style="color: #0000ff;">use</span><span style="color: #000000;"> yii\base\Event;

Event</span>::on(Foo::className(), Foo::EVENT_HELLO, <span style="color: #0000ff;">function</span> (<span style="color: #800080;">$event</span><span style="color: #000000;">) {
    </span><span style="color: #0000ff;">echo</span> <span style="color: #800080;">$event</span>->sender;  <span style="color: #008000;">//</span><span style="color: #008000;"> 显示 "app\models\Foo"</span>
<span style="color: #000000;">});

Event</span>::trigger(Foo::className(), Foo::EVENT_HELLO);

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

Note: 因为类级别的处理器响应类和其子类的所有实例触发的事件，必须谨慎使用，尤其是底层的基类，如 [[yii\base\Object]]。

移除类级别的事件处理器只需调用[[yii\base\Event::off()]]，如：

<span style="color: #008000;">//</span><span style="color: #008000;"> 移除 $handler</span>
Event::off(Foo::className(), Foo::EVENT_HELLO, <span style="color: #800080;">$handler</span><span style="color: #000000;">);

</span><span style="color: #008000;">//</span><span style="color: #008000;"> 移除 Foo::EVENT_HELLO 事件的全部处理器</span>
Event::off(Foo::className(), Foo::EVENT_HELLO);

全局事件

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

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

<span style="color: #0000ff;">use</span><span style="color: #000000;"> Yii;
</span><span style="color: #0000ff;">use</span><span style="color: #000000;"> yii\base\Event;
</span><span style="color: #0000ff;">use</span><span style="color: #000000;"> app\components\Foo;

Yii</span>::<span style="color: #800080;">$app</span>->on('bar', <span style="color: #0000ff;">function</span> (<span style="color: #800080;">$event</span><span style="color: #000000;">) {
    </span><span style="color: #0000ff;">echo</span> <span style="color: #008080;">get_class</span>(<span style="color: #800080;">$event</span>->sender);  <span style="color: #008000;">//</span><span style="color: #008000;"> 显示 "app\components\Foo"</span>
<span style="color: #000000;">});

Yii</span>::<span style="color: #800080;">$app</span>->trigger('bar', <span style="color: #0000ff;">new</span> Event(['sender' => <span style="color: #0000ff;">new</span> Foo]));

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

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