事件

Laravel 中文文档 / 综合话题

事件

简介

Laravel 的事件提供了简单的观察者实现,允许您订阅或监听应用中发生的各种事件。通常来说,事件类储存在 app/Events 目录中,而对应的监听器储存在 app/Listeners 目录中。如果在应用中没有看到这些目录也不用担心,因为它们会在使用 Artisan 终端命令生成事件和监听器时自动创建。

事件为应用的多方面解耦提供了很好的方式,因为单个事件可以有多个不依赖彼此的监听器。例如,您可能希望在每次订单发货后给用户发送 Slack 通知。应该触发一个 OrderShipped 事件,由监听器接收该事件并发送 Slack 通知,而不是将订单处理代码与 Slack 通知代码耦合在一起。

注册事件 & 监听器

Laravel 包含的 EventServiceProvider 为注册所有应用的事件监听器提供了一个方便的地方。listen 属性包含一个所有事件(键)和对应的监听器(值)的数组。当然,可以根据应用需要添加多个事件到此数组中。例如,我们添加一个 OrderShipped 事件:

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

生成事件 & 监听器

当然,为每个事件和监听器手动创建文件很麻烦。应该将监听器和事件添加到 EventServiceProvider,然后使用 event:generate 命令。此命令会自动生成所有列在 EventServiceProvider 中的事件或监听器。当然,已存在的事件和监听器会原封不动的保留:

php artisan event:generate

手动注册事件

通常情况下,事件应该通过 EventServiceProvider$listen 数组注册;不过,您也可以在 EventServiceProviderboot 方法中手动注册基于闭包的事件:

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

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

通配符事件监听器

甚至还可以使用 * 作为通配符参数注册监听器,允许您捕获同一监听器的多个事件。通配符监听器接收事件名称作为其第一个参数,以及完整的事件数据数组作为其第二个参数:

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

定义事件

事件类是包含事件相关信息的一个数据容器。例如,假设我们生成的 OrderShipped 事件接收一个 Eloquent ORM 对象:

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 方法中,可以执行响应事件所需的任何操作:

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 获取订单
    }
}

事件监听器也可以在其构造函数中对任何所需依赖使用类型提示。所有事件监听器都通过 Laravel 的 服务容器 解析,因此会自动注入依赖。

停止事件传播

有时,可能希望停止事件传播到其它监听器。可以通过在监听器的 handle 方法中返回 false 来完成此操作。

事件监听器队列

如果监听器要执行一个缓慢的任务,例如发送电子邮件或者发起 HTTP 请求,那么队列监听器会很有帮助。在使用队列监听器之前,确保在服务器或本地开发环境中 配置队列 并启动了队列监听器。

要指定监听器在队列中运行,需要将 ShouldQueue 接口添加到监听器类。通过 Artisan 命令 event:generate 生成的监听器已经将此接口引入到当前命名空间,因此可以直接使用:

namespace App\Listeners;

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

class SendShipmentNotification implements ShouldQueue
{
    //
}

就这样!现在,当监听器被事件调用时,会使用 Laravel 的 队列系统 由事件分发器自动添加到队列。如果通过队列执行事件监听器时没有抛出异常,队列任务会在处理完成后自动被删除。

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

如果要自定义事件监听器使用的队列连接和队列名称,可以在监听器类中定义 $connection$queue 属性:

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';
}

手动访问队列

如果需要手动访问监听器底层队列任务的 deleterelease 方法,可以使用 Illuminate\Queue\InteractsWithQueue Trait 完成此操作。生成的监听器默认引入了此 Trait,并提供这些方法:

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 方法接收事件的实例和导致失败的异常:

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 辅助函数是全局可用的,因此可以在应用的任何地方调用:

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

        // 订单配送逻辑

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

当测试时,在不实际触发监听器的情况下断言某些事件被分发时会很有用。Laravel 内置的测试辅助方法 使得它很容易。

事件订阅者

编写事件订阅者

事件订阅者是一个可以在类自身中订阅多个事件的类,允许您在单个类中定义多个事件处理方法。订阅者应该定义一个 subscribe 方法,此方法接收一个事件分发器的实例。可以在给定的分发器上调用 listen 方法注册事件监听器:

namespace App\Listeners;

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

    /**
     * 处理用户退出登录事件
     */
    public function onUserLogout($event) {}

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

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

注册事件订阅者

编写订阅者后,就可以将其注册到事件分发器。可以使用 EventServiceProvider$subscribe 属性注册订阅者。例如,我们添加 UserEventSubscriber 到列表中:

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',
    ];
}
  上一篇 下一篇  

作者:ilaoniu

牛哥,俗称哞哞。单纯的九零后理工小青年。喜欢折腾,爱玩,爱安卓,爱音乐,爱游戏,爱电影,爱旅游...