事件系统

6.x

8.5 8.x 7.x 6.x 5.8 5.7 5.6 5.5 5.4 5.3 5.2 5.1

本文档最新版为 8.5，旧版本可能放弃维护，推荐阅读最新版！

Events

简介
注册事件 & 监听器
定义事件
定义监听器
事件监听器队列
- 手动访问队列
- 处理失败任务
分发事件
事件订阅者
- 编写事件订阅者
- 注册事件订阅者

事件系统介绍

Laravel的事件提供了一个简单的观察者实现，允许你在应用中订阅和监听各种发生的事件。事件类通常放在app/Events目录下，而这些事件类的监听器则放在app/Listeners目录下。如果在你的应用中你没有看到这些目录，不用担心，它们会在你使用 Artisan 控制台命令生成事件与监听器的时候自动创建。
事件系统为应用各个方面的解耦提供了非常棒的方法，因为单个事件可以拥有多个互不依赖的监听器。举个例子，你可能希望每次订单发货时向用户推送一个 Slack 通知。你可以简单地发起一个可以被监听器接收并转化为 Slack 通知的 OrderShipped 事件，而不是将订单处理代码和 Slack 通知代码耦合在一起。

注册事件和监听器

Laravel 应用中的 EventServiceProvider 为注册所有的事件监听器提供了一个便利的场所。其中， listen 属性包含了所有事件 (键) 以及事件对应的监听器 (值) 的数组。当然，你可以根据应用的需要，添加多个事件到 listen属性包含的数组中。举个例子，我们来添加一个 OrderShipped 事件：

/**
 * 应用程序的事件监听器映射
 *
 * @var array
 */
protected $listen = [
    'App\Events\OrderShipped' => [
        'App\Listeners\SendShipmentNotification',
    ],
];

生成事件 & 监听器

当然，手动创建事件和监听器的文件是件麻烦事。而在这里，你只需要将监听器和事件添加到 EventServiceProvider 中，而后使用 event:generate 命令。这个命令会生成在 EventServiceProvider 中列出的所有事件和监听器。当然，已经存在的事件和监听器将保持不变：

php artisan event:generate

手动注册事件

通常，事件是在 EventServiceProvider 的 $listen 数组中注册；然而，你也可以在 EventServiceProvider 的 boot 方法中手动注册基于闭包的这些事件：

/**
 * 注册应用中的其它事件
 *
 * @return void
 */
public function boot()
{
    parent::boot();

    Event::listen('event.name', function ($foo, $bar) {
        //
    });
}

通配符事件监听器

你可以在注册监听器时使用 * 作为通配符参数，这样可以在同一个监听器上捕获多个事件。通配符监听器接收事件名作为其第一个参数，并将整个事件数据数组作为其第二个参数：

Event::listen('event.*', function ($eventName, array $data) {
    //
});

事件发现

注意：事件发现可用于Laravel 5.8.9或更高版本。

您可以启用自动事件发现，而不是在EventServiceProvider的$listen数组中手动注册事件和监听器。启用事件发现后，Laravel将通过扫描应用程序的Listeners目录自动查找并注册您的事件和侦听器。此外，EventServiceProvider中列出的任何明确定义的事件仍将被注册。

Laravel通过使用反射扫描监听器类来查找事件监听器。当Laravel找到以handle开头的监听器类方法时，Laravel会将这些方法注册为方法签名中类型提示的事件的事件监听器：

use App\Events\PodcastProcessed;

class SendPodcastProcessedNotification
{
    /**
     * 处理给定的事件。
     *
     * @param  \App\Events\PodcastProcessed
     * @return void
     */
    public function handle(PodcastProcessed $event)
    {
        //
    }
}

默认情况下禁用事件发现，但您可以通过覆盖应用程序的EventServiceProvider的shouldDiscoverEvents方法来启用它：

/**
 * 确定是否应自动发现事件和侦听器。
 *
 * @return bool
 */
public function shouldDiscoverEvents()
{
    return true;
}

默认情况下，将扫描应用程序的Listeners目录中的所有监听器。如果要定义扫描的其他目录，可以覆盖EventServiceProvider中的discoverEventsWithin方法：

/**
 * 获取应该用于发现事件的监听器目录
 *
 * @return array
 */
protected function discoverEventsWithin()
{
    return [
        $this->app->path('Listeners'),
    ];
}

在生产中，您可能不希望框架在每个请求上扫描所有监听器。因此，在部署过程中，您应该运行event：cache Artisan命令来缓存应用程序的所有事件和监听器的列表。框架将使用此列表来加速事件注册过程。 event：clear命令可用于销毁缓存。

提示：event：list命令可用于显示应用程序注册的所有事件和监听器的列表。

定义事件

事件类是一个保存与事件相关信息的容器。例如，假设我们生成的 OrderShipped 事件接收一个 Eloquent ORM 对象：

<?php

namespace App\Events;

use App\Order;
use Illuminate\Queue\SerializesModels;

class OrderShipped
{
    use SerializesModels;

    public $order;

    /**
     * 创建一个事件实例
     *
     * @param  \App\Order  $order
     * @return void
     */
    public function __construct(Order $order)
    {
        $this->order = $order;
    }
}

如你所见，这个事件类中没有包含其它逻辑。它只是一个购买的 Order 的实例的容器。如果使用 PHP 的 serialize 函数序列化事件对象，事件使用的 SerializesModels trait 将会优雅地序列化任何 Eloquent 模型。

定义监听器

接下来，让我们看一下例子中事件的监听器。事件监听器在 handle 方法中接收实例。 event:generate 命令会自动加载正确的事件类，并且在 handle 方法中加入事件的类型提示。在 handle 方法中，你可以执行任何必要的响应事件的操作：

<?php

namespace App\Listeners;

use App\Events\OrderShipped;

class SendShipmentNotification
{
    /**
     * 创建事件监听器
     *
     * @return void
     */
    public function __construct()
    {
        //
    }

    /**
     * 处理事件
     *
     * @param  \App\Events\OrderShipped  $event
     * @return void
     */
    public function handle(OrderShipped $event)
    {
         // 使用 $event->order 来访问 order ...
    }
}

提示: 你的事件监听器也可以在构造函数中加入任何依赖关系的类型提示。所有的事件监听器都是通过 Laravel 的服务容器解析的, 因此所有的依赖都将会被自动注入.

停止事件传播

有时，你可以通过在监听器的 handle 方法中返回 false 来阻止事件被其它的监听器获取。

事件监听器队列

如果你的监听器中要执行诸如发送电子邮件或发出HTTP请求之类的耗时任务，你可以将任务丢给队列处理。在开始使用队列监听器之前，请确保在你的服务器或者本地开发环境中能够配置队列并启动一个队列监听器。

要指定监听器启动队列，你可以在监听器类中实现 ShouldQueue 接口。由 Artisan 命令 event:generate 生成的监听器已经将此接口导入到当前命名空间中，因此你可以直接使用：

<?php

namespace App\Listeners;

use App\Events\OrderShipped;
use Illuminate\Contracts\Queue\ShouldQueue;

class SendShipmentNotification implements ShouldQueue
{
    //
}

That's it！现在，当这个监听器被事件调用时，事件调度器会自动使用Laravel的队列系统自动排队。如果在队列中执行监听器时没有抛出异常，任务会在执行完成后自动从队列中删除。

自定义队列连接 & 队列名称

如果你想要自定义事件监听器所使用的队列的连接和名称，你可以在监听器类中定义 $connection， $queue 或 $delay 属性：

<?php

namespace App\Listeners;

use App\Events\OrderShipped;
use Illuminate\Contracts\Queue\ShouldQueue;

class SendShipmentNotification implements ShouldQueue
{
    /**
     * 任务连接名称。
     *
     * @var string|null
     */
    public $connection = 'sqs';

    /**
     * 任务发送到的队列的名称.
     *
     * @var string|null
     */
    public $queue = 'listeners';

    /**
     * 处理任务的延迟时间.
     *
     * @var int
     */
    public $delay = 60;
}

条件监听队列

有时，你可能需要根据某些运行时的数据（满足某些条件）对监听器进行排队，为此，可以在侦听器中添加shouldQueue方法，以确定是否应该将监听器排队并同步执行：

<?php

namespace App\Listeners;

use App\Events\OrderPlaced;
use Illuminate\Contracts\Queue\ShouldQueue;

class RewardGiftCard implements ShouldQueue
{
    /**
     * 奖励礼品卡给客户
     *
     * @param  \App\Events\OrderPlaced  $event
     * @return void
     */
    public function handle(OrderPlaced $event)
    {
        //
    }

    /**
     * 确定监听器是否应加入队列
     *
     * @param  \App\Events\OrderPlaced  $event
     * @return bool
     */
    public function shouldQueue(OrderPlaced $event)
    {
        return $event->order->subtotal >= 5000;
    }
}

手动访问队列

如果你需要手动访问监听器下面队列任务的 delete 和 release 方法，你可以通过使用 Illuminate\Queue\InteractsWithQueue trait 来实现。这个 trait 会默认加载到生成的监听器中，并提供对这些方法的访问：

<?php

namespace App\Listeners;

use App\Events\OrderShipped;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Contracts\Queue\ShouldQueue;

class SendShipmentNotification implements ShouldQueue
{
    use InteractsWithQueue;

    /**
     * 处理事件.
     *
     * @param  \App\Events\OrderShipped  $event
     * @return void
     */
    public function handle(OrderShipped $event)
    {
        if (true) {
            $this->release(30);
        }
    }
}

处理失败任务

有时事件监听器的队列任务可能会失败。如果监听器的队列任务超过了队列中定义的最大尝试次数，则会在监听器上调用 failed 方法。 failed 方法接收事件实例和导致失败的异常作为参数：

<?php

namespace App\Listeners;

use App\Events\OrderShipped;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Contracts\Queue\ShouldQueue;

class SendShipmentNotification implements ShouldQueue
{
    use InteractsWithQueue;

    /**
     * 处理事件.
     *
     * @param  \App\Events\OrderShipped  $event
     * @return void
     */
    public function handle(OrderShipped $event)
    {
        //
    }

    /**
     * 处理失败任务
     *
     * @param  \App\Events\OrderShipped  $event
     * @param  \Exception  $exception
     * @return void
     */
    public function failed(OrderShipped $event, $exception)
    {
        //
    }
}

分发事件

如果要分发事件，你可以将事件实例传递给辅助函数 event。该辅助函数将会把事件分发到所有该事件相应的已经注册了的监听器上。event 辅助函数可以全局使用，你可以在应用中的任何位置进行调用：

<?php

namespace App\Http\Controllers;

use App\Order;
use App\Events\OrderShipped;
use App\Http\Controllers\Controller;

class OrderController extends Controller
{
    /**
     * 将传递过来的订单发货
     *
     * @param  int  $orderId
     * @return Response
     */
    public function ship($orderId)
    {
        $order = Order::findOrFail($orderId);

        // Order shipment logic...

        event(new OrderShipped($order));
    }
}

Tip：在测试时，只需要断言特定事件被分发，而不需要真正地触发监听器。 Laravel 的内置测试辅助函数可以轻松做到这一点.

事件订阅者

编写事件订阅者

事件订阅者是可以在自身内部订阅多个事件的类，即能够在单个类中定义多个事件处理器。订阅者应该定义一个 subscribe 方法，这个方法接收一个事件分发器实例。你可以调用给定事件分发器上的 listen 方法来注册事件监听器：

<?php

namespace App\Listeners;

class UserEventSubscriber
{
    /**
     * 处理用户登录事件
     */
    public function handleUserLogin($event) {}

    /**
     * 处理用户注销事件
     */
    public function handleUserLogout($event) {}

    /**
     * 为订阅者注册监听器.
     *
     * @param  \Illuminate\Events\Dispatcher  $events
     */
    public function subscribe($events)
    {
        $events->listen(
            'Illuminate\Auth\Events\Login',
            'App\Listeners\UserEventSubscriber@handleUserLogin'
        );

        $events->listen(
            'Illuminate\Auth\Events\Logout',
            'App\Listeners\UserEventSubscriber@handleUserLogout'
        );
    }
}

注册事件订阅者

在编写完订阅者之后，就可以通过事件分发器对订阅者进行注册。你可以在 EventServiceProvider 中的 $subscribe 属性中注册订阅者。例如，让我们将 UserEventSubscriber 添加到数组列表中：

<?php

namespace App\Providers;

use Illuminate\Foundation\Support\Providers\EventServiceProvider as ServiceProvider;

class EventServiceProvider extends ServiceProvider
{
    /**
     * 应用中事件监听器的映射。
     *
     * @var array
     */
    protected $listen = [
        //
    ];

    /**
     * 需要注册的订阅者类。
     *
     * @var array
     */
    protected $subscribe = [
        'App\Listeners\UserEventSubscriber',
    ];
}

本文章首发在网站上。

原文地址：cndocs/6.x/eve...

译文地址：cndocs/6.x/eve...

事件系统 6.x 8.5 8.x 7.x 6.x 5.8 5.7 5.6 5.5 5.4 5.3 5.2 5.1

Events

事件系统介绍

注册事件和监听器

生成事件 & 监听器

手动注册事件

通配符事件监听器

事件发现

定义事件

定义监听器

停止事件传播

事件监听器队列

自定义队列连接 & 队列名称

条件监听队列

手动访问队列

处理失败任务

分发事件

事件订阅者

编写事件订阅者

注册事件订阅者

事件系统

6.x

8.5 8.x 7.x 6.x 5.8 5.7 5.6 5.5 5.4 5.3 5.2 5.1