Info
Content

事件

Created 4 years ago by 学院君, Updated 4 years ago    Revision #5    6064 views    0 likes    1 collects

简介

Laravel 事件提供了简单的观察者模式实现，允许你订阅和监听应用中的事件。事件类通常存放在 app/Events 目录，监听器存放在 app/Listeners。如果你在应用中没有看到这些目录，不要担心，它们会在你使用 Artisan 命令生成事件和监听器的时候自动创建。

事件为应用功能模块解耦提供了行之有效的解决办法，因为单个事件可以有多个监听器而这些监听器之间并不相互依赖。例如，你可能想要在每次订单发送时给用户发送一个 Slack 通知，有了事件之后，你大可不必将订单处理代码和 Slack 通知代码耦合在一起，而只需要简单触发一个可以被监听器接收并处理为 Slack 通知的 OrderShipped 事件即可。

注册事件/监听器

Laravel 自带的 EventServiceProvider 为事件监听器注册提供了方便之所。其中的 listen 属性包含了事件（键）和对应监听器（值）数组。如果应用需要，你可以添加多个事件到该数组。下面让我们添加一个 OrderShipped 事件：

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

生成事件/监听器类

当然，手动为每个事件和监听器创建文件是很笨重的，取而代之地，我们只需简单添加监听器和事件到 EventServiceProvider 然后运行 event:generate 命令。该命令将会生成罗列在 EventServiceProvider 中的所有事件和监听器。当然，已存在的事件和监听器不会被重复创建：

php artisan event:generate

手动注册事件

通常，我们需要通过 EventServiceProvider 的 $listen 数组注册事件，此外，你还可以在 EventServiceProvider 的 boot 方法中手动注册基于闭包的事件：

use App\Events\PodcastProcessed;

/**
 * 注册应用的其它事件.
 *
 * @return void
 */
public function boot()
{
    Event::listen(function (PodcastProcessed $event) {
        //
    });
}

队列化匿名事件监听器

手动注册事件监听器时，你可以将监听器闭包通过 Illuminate\Events\queueable 函数调用来告知 Laravel 使用队列执行这个监听器：

use App\Events\PodcastProcessed;
use function Illuminate\Events\queueable;
use Illuminate\Support\Facades\Event;

/**
 * Register any other events for your application.
 *
 * @return void
 */
public function boot()
{
    Event::listen(queueable(function (PodcastProcessed $event) {
        //
    }));
}

和队列任务一样，你可以使用 onConnection、onQueue 和 delay 方法来自定义队列监听器的执行：

Event::listen(queueable(function (PodcastProcessed $event) {
    //
})->onConnection('redis')->onQueue('podcasts')->delay(now()->addSeconds(10)));

如果你想要处理匿名的队列化事件监听器执行失败，可以在定义 queueable 监听器时提供一个闭包到 catch 方法：

use App\Events\PodcastProcessed;
use function Illuminate\Events\queueable;
use Illuminate\Support\Facades\Event;
use Throwable;

Event::listen(queueable(function (PodcastProcessed $event) {
    //
})->catch(function (PodcastProcessed $event, Throwable $e) {
    // The queued listener failed...
}));

通配符事件监听器

你甚至还可以使用通配符*来注册监听器，这样就可以通过同一个监听器捕获多个事件。通配符监听器接收整个事件数据数组作为参数：

$events->listen('event.*', function ($eventName, array $data) {
    //
});

事件自动发现

除了在 EventServiceProvider 的 $listen 数组中手动注册事件及对应监听器之外，还可以开启自动事件发现。当事件发现开启后，Laravel 将会通过遍历应用的 Listeners 目录自动查找并注册事件及对应监听器。此外，任何显式定义在 EventServiceProvider 的列表中的事件仍然会被注册。

Laravel 使用反射遍历监听器类来发现事件监听器，当 Laravel 发现某个监听器类方法以 handle 开头，将会从方法签名中提取类型提示指定的事件，然后将该方法作为该事件的事件监听器：

use App\Events\PodcastProcessed;

class SendPodcastProcessedNotification
{
    /**
     * Handle the given event.
     *
     * @param  \App\Events\PodcastProcessed
     * @return void
     */
    public function handle(PodcastProcessed $event)
    {
        //
    }
}

事件发现默认是禁止的，你可以通过重写 EventServiceProvider 的 shouldDiscoverEvents 方法来开启它：

/**
 * Determine if events and listeners should be automatically discovered.
 *
 * @return bool
 */
public function shouldDiscoverEvents()
{
    return true;
}

默认情况下，所有位于应用监听器目录下的监听器类都会被遍历，如果你想要添加额外的需要遍历的目录，可以重写 EventServiceProvider 的 discoverEventsWithin 方法：

/**
 * Get the listener directories that should be used to discover events.
 *
 * @return array
 */
protected function discoverEventsWithin()
{
    return [
        $this->app->path('Listeners'),
    ];
}

在生产环境中，你可能不想要框架每次请求都要遍历所有监听器。因此，在部署过程中，你可以运行 Artisan 命令 event:cache 来缓存应用事件和监听器的清单（manifest），框架会使用该清单来加速事件注册流程。相对的，可以通过 event:clear 命令来清除缓存。

注：event:list 命令可用于显示应用中事件和对应注册的监听器列表。

定义事件

事件类是一个处理与事件相关的简单数据容器，例如，假设我们生成的 OrderShipped 事件接收一个 Eloquent ORM 对象：

<?php

namespace App\Events;

use App\Models\Order;
use Illuminate\Broadcasting\InteractsWithSockets;
use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;

class OrderShipped
{
    use Dispatchable, InteractsWithSockets, SerializesModels;

    public $order;

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

正如你所看到的，该事件类不包含任何特定逻辑，只是一个存放被购买的 Order 对象的容器，如果事件对象被序列化的话，事件使用的 SerializesModels trait 将会使用 PHP 的 serialize 函数序列化所有 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 访问订单...
    }
}

注：事件监听器还可以在构造器中类型提示任何需要的依赖，所有事件监听器通过服务容器解析，所以依赖会自动注入。

停止事件继续往下传播

有时候，你希望停止事件被传播到其它监听器，你可以通过从监听器的 handle 方法中返回 false 来实现。

事件监听器队列

如果监听器将要执行耗时任务比如发送邮件或者发送 HTTP 请求，那么将监听器放到队列是一个不错的选择。在队列化监听器之前，确保已经配置好队列并且在服务器或本地环境启动一个队列监听器。

要指定某个监听器需要放到队列，只需要让监听器类实现 ShouldQueue 接口即可，通过 Artisan 命令 event:generate 生成的监听器类已经将这个接口导入当前命名空间，所有你可以直接拿来使用：

<?php

namespace App\Listeners;

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

class SendShipmentNotification implements ShouldQueue
{
    //
}

就是这么简单！当这个监听器被调用的时候，将会使用 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;
}

如果你想要在运行时定义监听器队列，可以在监听器上定义 viaQueue 方法：

/**
 * 获取监听器队列的名称
 *
 * @return string
 */
public function viaQueue()
{
    return 'listeners';
}

按条件推送监听器到队列

有时候，你可能需要基于一些运行时数据才能判断某个监听器是否需要推送到队列，这个时候，就需要在监听器中添加一个 shouldQueue 方法，该方法用于判断此监听器会被推送到队列还是同步执行：

<?php

namespace App\Listeners;

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

class RewardGiftCard implements ShouldQueue
{
    /**
     * Reward a gift card to the customer.
     *
     * @param  \App\Events\OrderPlaced  $event
     * @return void
     */
    public function handle(OrderPlaced $event)
    {
        //
    }

    /**
     * Determine whether the listener should be queued.
     *
     * @param  \App\Events\OrderPlaced  $event
     * @return bool
     */
    public function shouldQueue(OrderPlaced $event)
    {
        return $event->order->subtotal >= 5000;
    }
}

手动访问队列

如果你需要手动访问底层队列任务的 delete 和 release 方法，在生成的监听器中，默认导入的 Illuminate\Queue\InteractsWithQueue trait 为这两个方法提供了访问权限：

<?php

namespace App\Listeners;

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

class SendShipmentNotification implements ShouldQueue
{
    use InteractsWithQueue;

    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;

    public function handle(OrderShipped $event)
    {
        //
    }

    public function failed(OrderShipped $event, $exception)
    {
        //
    }
}

分发事件

要分发一个事件，可以传递事件实例到辅助函数 event，这个辅助函数会分发事件到所有注册的监听器。由于辅助函数 event 全局有效，所以可以在应用的任何地方调用它：

<?php

namespace App\Http\Controllers;

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

class OrderController extends Controller
{
    /**
     * 处理给定订单.
     *
     * @param  int  $orderId
     * @return Response
     */
    public function ship($orderId)
    {
        $order = Order::findOrFail($orderId);

        // 订单处理逻辑...

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

或者，如果事件类使用了 Illuminate\Foundation\Events\Dispatchable Trait，你可以调用对应事件上的静态 dispatch 方法。传递给 dispatch 方法的所有参数都会被传递给事件构造器：

OrderShipped::dispatch($order);

注：测试的时候，只需要断言特定事件被分发，无需真正触发监听器，Laravel 自带的测试函数让这一实现轻而易举。

事件订阅者

编写事件订阅者

事件订阅者是指那些在类本身中订阅多个事件的类，通过事件订阅者你可以在单个类中定义多个事件处理器。订阅者需要定义一个 subscribe 方法，该方法中传入一个事件分发器实例。你可以在给定的分发器中调用 listen 方法注册事件监听器：

<?php

namespace App\Listeners;

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

    /**
     * 处理用户退出事件.
     */
    public function handleUserLogout($event) {}

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

        $events->listen(
            'Illuminate\Auth\Events\Logout',
            [UserEventSubscriber::class, 'handleUserLogout']
        );
    }
}

或者，订阅者的 subscribe 方法可以返回事件与处理器的映射关系数组，这种情况下，事件监听器映射关系会自动注册：

use Illuminate\Auth\Events\Login;
use Illuminate\Auth\Events\Logout;

/**
 * Register the listeners for the subscriber.
 *
 * @return array
 */
public function subscribe()
{
    return [
        Login::class => [
          [UserEventSubscriber::class, 'handleUserLogin']
        ],
        Logout::class => [
          [UserEventSubscriber::class, 'handleUserLogout']
        ],
    ];
}

注册事件订阅者

编写好订阅者之后，就可以通过事件分发器对订阅者进行注册，你可以使用 EventServiceProvider 提供的 $subcribe 属性来注册订阅者。例如，让我们添加一个 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',
    ];
}
Laravel
8.x
文档
事件
Event
监听器
队列
自动发现
事件监听
事件分发
订阅
映射
Vote Vote Cancel Collect Collect Cancel

<< 上一篇: 契约

>> 下一篇: 文件存储

4 Comments
#1    jjkkopq   jjkkopq commented 4 years ago •  Updated 4 years ago by jjkkopq

编写事件订阅者 的部分写错了 https://laravel.com/docs/8.x/events#writing-event-subscribers

#2    学院君   学院君 commented 4 years ago
In reply to #1

哪里错了？

#3    jjkkopq   jjkkopq commented 4 years ago •  Updated 4 years ago by jjkkopq
In reply to #2

1.这里对映换下 onUserLogin => handleUserLogin, onUserLogout => handleUserLogout,

2.事件监听器映射关系会自动注册， 这里要再套一层中括号

public function subscribe()
{
    return [
        Login::class => [
                 [UserEventSubscriber::class, 'handleUserLogin']
        ],
        Logout::class => [
                 [UserEventSubscriber::class, 'handleUserLogout']
        ],
    ];
}
#4    学院君   学院君 commented 4 years ago
In reply to #3

得 还真是 不仔细看还没看出来 感谢反馈 已修正 ? 之前版本这个地方也要调整 ?

登录后即可添加评论