事件 – 乌鸦嘴文档中心

介绍

Laravel 的事件提供了一个简单的观察者模式实现，允许您订阅并监听应用程序中发生的各种事件。事件类通常存储在 app/Events 目录中，而它们的监听器存储在 app/Listeners 中。如果您在应用程序中没有看到这些目录，不必担心，因为当您使用 Artisan 控制台命令生成事件和监听器时，它们会为您创建。

事件是将应用程序的各个方面解耦的好方法，因为单个事件可以有多个相互不依赖的监听器。例如，您可能希望在每次订单发货时向用户发送 Slack 通知。您可以引发一个 App\Events\OrderShipped 事件，而不是将订单处理代码与 Slack 通知代码耦合，监听器可以接收该事件并用于发送 Slack 通知。

生成事件和监听器

要快速生成事件和监听器，您可以使用 make:event 和 make:listener Artisan 命令：

php artisan make:event PodcastProcessed
 
php artisan make:listener SendPodcastNotification --event=PodcastProcessed

为了方便起见，您也可以在不添加其他参数的情况下调用 make:event 和 make:listener Artisan 命令。当您这样做时，Laravel 会自动提示您输入类名，并且在创建监听器时，提示您输入它应该监听的事件：

php artisan make:event
 
php artisan make:listener

注册事件和监听器

事件发现

默认情况下，Laravel 将通过扫描应用程序的 Listeners 目录自动查找并注册您的事件监听器。当 Laravel 找到任何以 handle 或 __invoke 开头的监听器类方法时，Laravel 将把这些方法注册为方法签名中类型提示的事件的事件监听器：

use App\Events\PodcastProcessed;

class SendPodcastNotification
{
    /**
     * 处理给定的事件。
     */
    public function handle(PodcastProcessed $event): void
    {
        //...
    }
}

如果您计划将监听器存储在不同的目录或多个目录中，您可以在应用程序的 bootstrap/app.php 文件中使用 withEvents 方法指示 Laravel 扫描这些目录：

->withEvents(discover: [
    __DIR__.'/../app/Domain/Orders/Listeners',
])

可以使用 event:list 命令列出应用程序中注册的所有监听器：

php artisan event:list

生产环境中的事件发现

为了提高应用程序的速度，您应该使用 optimize 或 event:cache Artisan 命令缓存应用程序所有监听器的清单。通常，此命令应作为应用程序部署过程的一部分运行。该框架将使用此清单来加快事件注册过程。可以使用 event:clear 命令销毁事件缓存。

手动注册事件

使用 Event 外观，您可以在应用程序的 AppServiceProvider 的 boot 方法中手动注册事件及其相应的监听器：

use App\Domain\Orders\Events\PodcastProcessed;
use App\Domain\Orders\Listeners\SendPodcastNotification;
use Illuminate\Support\Facades\Event;

/**
 * 引导任何应用程序服务。
 */
public function boot(): void
{
    Event::listen(
        PodcastProcessed::class,
        SendPodcastNotification::class,
    );
}

可以使用 event:list 命令列出应用程序中注册的所有监听器：

php artisan event:list

闭包监听器

通常，监听器被定义为类；然而，您也可以在应用程序的 AppServiceProvider 的 boot 方法中手动注册基于闭包的事件监听器：

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

/**
 * 引导任何应用程序服务。
 */
public function boot(): void
{
    Event::listen(function (PodcastProcessed $event) {
        //...
    });
}

可排队的匿名事件监听器

在注册基于闭包的事件监听器时，您可以将监听器闭包包装在 Illuminate\Events\queueable 函数中，以指示 Laravel 使用队列执行监听器：

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

/**
 * 引导任何应用程序服务。
 */
public function boot(): void
{
    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 方法提供一个闭包。这个闭包将接收事件实例和导致监听器失败的 Throwable 实例：

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) {
    // 排队监听器失败...
}));

通配符事件监听器

您还可以使用 * 字符作为通配符参数注册监听器，允许您在同一个监听器上捕获多个事件。通配符监听器将事件名称作为其第一个参数，将整个事件数据数组作为其第二个参数：

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

定义事件

事件类本质上是一个数据容器，用于保存与事件相关的信息。例如，假设一个 App\Events\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 function __construct(
        public Order $order,
    ) {}
}

如您所见，这个事件类不包含逻辑。它是购买的 App\Models\Order 实例的容器。如果事件对象使用 PHP 的 serialize 函数进行序列化，例如在使用排队监听器时，事件使用的 SerializesModels 特征将优雅地序列化任何 Eloquent 模型。

定义监听器

接下来，让我们看一下我们示例事件的监听器。事件监听器在其 handle 方法中接收事件实例。当使用 --event 选项调用 make:listener Artisan 命令时，它将自动导入正确的事件类，并在 handle 方法中对事件进行类型提示。在 handle 方法中，您可以执行任何必要的操作来响应事件：

<?php

namespace App\Listeners;

use App\Events\OrderShipped;

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

    /**
     * 处理事件。
     */
    public function handle(OrderShipped $event): void
    {
        // 使用 $event->order 访问订单...
    }
}

[!注意]
您的事件监听器也可以在其构造函数上类型提示它们所需的任何依赖项。所有事件监听器都通过 Laravel 服务容器进行解析，因此依赖项将自动注入。

停止事件的传播

有时，您可能希望停止事件向其他侦听器的传播。您可以通过从侦听器的 handle 方法返回 false 来实现。

排队事件侦听器

如果您的侦听器要执行诸如发送电子邮件或进行 HTTP 请求等缓慢任务，那么对侦听器进行排队可能会很有益。在使用排队侦听器之前，请确保配置您的队列并在您的服务器或本地开发环境中启动一个队列工作者。

要指定一个侦听器应被排队，将 ShouldQueue 接口添加到侦听器类中。通过 make:listener Artisan 命令生成的侦听器已经将此接口导入到当前命名空间中，因此您可以立即使用它：

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

如果您想在运行时定义侦听器的队列连接、队列名称或延迟，可以在侦听器上定义 viaConnection、viaQueue 或 withDelay 方法：

/**
 * 获取侦听器的队列连接的名称。
 */
public function viaConnection(): string
{
    return 'sqs';
}

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

/**
 * 获取作业应被处理之前的秒数。
 */
public function withDelay(OrderShipped $event): int
{
    return $event->highPriority? 0 : 60;
}

有条件地排队侦听器

有时，您可能需要根据仅在运行时可用的某些数据来确定侦听器是否应被排队。要实现此目的，可以向侦听器添加一个 shouldQueue 方法来确定侦听器是否应被排队。如果 shouldQueue 方法返回 false，则侦听器不会被排队：

<?php

namespace App\Listeners;

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

class RewardGiftCard implements ShouldQueue
{
    /**
     * 向客户奖励礼品卡。
     */
    public function handle(OrderCreated $event): void
    {
        //...
    }

    /**
     * 确定侦听器是否应被排队。
     */
    public function shouldQueue(OrderCreated $event): bool
    {
        return $event->order->subtotal >= 5000;
    }
}

手动与队列交互

如果您需要手动访问侦听器底层队列作业的 delete 和 release 方法，可以使用 Illuminate\Queue\InteractsWithQueue 特征。此特征在生成的侦听器中默认导入，并提供对这些方法的访问：

<?php

namespace App\Listeners;

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

class SendShipmentNotification implements ShouldQueue
{
    use InteractsWithQueue;

    /**
     * 处理事件。
     */
    public function handle(OrderShipped $event): void
    {
        if (true) {
            $this->release(30);
        }
    }
}

排队事件侦听器和数据库事务

当在数据库事务中分发排队侦听器时，它们可能会在数据库事务提交之前由队列处理。当发生这种情况时，在数据库事务期间对模型或数据库记录所做的任何更新可能尚未反映在数据库中。此外，在事务中创建的任何模型或数据库记录可能在数据库中不存在。如果您的侦听器依赖于这些模型，则在处理分发排队侦听器的作业时可能会发生意外错误。

如果您的队列连接的 after_commit 配置选项设置为 false，您仍然可以通过在侦听器类上实现 ShouldQueueAfterCommit 接口来指示应在所有打开的数据库事务提交后分发特定的排队侦听器：

<?php

namespace App\Listeners;

use Illuminate\Contracts\Queue\ShouldQueueAfterCommit;
use Illuminate\Queue\InteractsWithQueue;

class SendShipmentNotification implements ShouldQueueAfterCommit
{
    use InteractsWithQueue;
}

[!NOTE]
要了解有关解决这些问题的更多信息，请查看有关排队作业和数据库事务的文档。

处理失败的作业

有时您的排队事件侦听器可能会失败。如果排队侦听器超过您的队列工作者定义的最大尝试次数，则会在您的侦听器上调用 failed 方法。failed 方法接收事件实例和导致失败的 Throwable：

<?php

namespace App\Listeners;

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

class SendShipmentNotification implements ShouldQueue
{
    use InteractsWithQueue;

    /**
     * 处理事件。
     */
    public function handle(OrderShipped $event): void
    {
        //...
    }

    /**
     * 处理作业失败。
     */
    public function failed(OrderShipped $event, Throwable $exception): void
    {
        //...
    }
}

指定排队侦听器的最大尝试次数

如果您的一个排队侦听器遇到错误，您可能不希望它无限期地不断重试。因此，Laravel 提供了多种方法来指定侦听器可以尝试的次数或时间。

您可以在侦听器类上定义一个 $tries 属性来指定在被认为失败之前侦听器可以尝试的次数：

<?php

namespace App\Listeners;

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

class SendShipmentNotification implements ShouldQueue
{
    use InteractsWithQueue;

    /**
     * 排队侦听器可以尝试的次数。
     *
     * @var int
     */
    public $tries = 5;
}

作为定义侦听器在失败之前可以尝试的次数的替代方法，您可以定义一个侦听器不应再被尝试的时间。这允许侦听器在给定的时间范围内被尝试任意次数。要定义侦听器不应再被尝试的时间，请向侦听器类添加一个 retryUntil 方法。此方法应返回一个 DateTime 实例：

use DateTime;

/**
 * 确定侦听器应超时的时间。
 */
public function retryUntil(): DateTime
{
    return now()->addMinutes(5);
}

分发事件

要分发事件，您可以在事件上调用静态的 dispatch 方法。此方法通过 Illuminate\Foundation\Events\Dispatchable 特征在事件上可用。传递给 dispatch 方法的任何参数都将传递给事件的构造函数：

<?php

namespace App\Http\Controllers;

use App\Events\OrderShipped;
use App\Http\Controllers\Controller;
use App\Models\Order;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;

class OrderShipmentController extends Controller
{
    /**
     * 发货给定的订单。
     */
    public function store(Request $request): RedirectResponse
    {
        $order = Order::findOrFail($request->order_id);

        // 订单发货逻辑...

        OrderShipped::dispatch($order);

        return redirect('/orders');
    }
}

如果您想有条件地分发事件，可以使用 dispatchIf 和 dispatchUnless 方法：

OrderShipped::dispatchIf($condition, $order);

OrderShipped::dispatchUnless($condition, $order);

[!NOTE]
在测试时，断言某些事件已被分发而实际上未触发其侦听器可能会很有帮助。Laravel 的内置测试助手使其变得轻而易举。

在数据库事务后分发事件

有时，您可能希望指示 Laravel 仅在活动数据库事务提交后才分发事件。为此，您可以在事件类上实现 ShouldDispatchAfterCommit 接口。

此接口指示 Laravel 在当前数据库事务提交后才分发事件。如果事务失败，事件将被丢弃。如果在分发事件时没有正在进行的数据库事务，则事件将立即分发：

<?php

namespace App\Events;

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

class OrderShipped implements ShouldDispatchAfterCommit
{
    use Dispatchable, InteractsWithSockets, SerializesModels;

    /**
     * 创建一个新的事件实例。
     */
    public function __construct(
        public Order $order,
    ) {}
}

事件订阅者

编写事件订阅者

事件订阅者是可以在订阅者类本身内订阅多个事件的类，允许您在单个类中定义多个事件处理程序。订阅者应定义一个 subscribe 方法，该方法将传递一个事件分发器实例。您可以在给定的分发器上调用 listen 方法来注册事件监听器：

<?php

namespace App\Listeners;

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

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

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

    /**
     * 为订阅者注册监听器。
     */
    public function subscribe(Dispatcher $events): void
    {
        $events->listen(
            Login::class,
            [UserEventSubscriber::class, 'handleUserLogin']
        );

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

如果您的事件监听器方法在订阅者本身内定义，您可能会发现从订阅者的 subscribe 方法中返回一个事件和方法名称的数组会更方便。Laravel 在注册事件监听器时会自动确定订阅者的类名：

<?php

namespace App\Listeners;

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

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

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

    /**
     * 为订阅者注册监听器。
     *
     * @return array<string, string>
     */
    public function subscribe(Dispatcher $events): array
    {
        return [
            Login::class => 'handleUserLogin',
            Logout::class => 'handleUserLogout',
        ];
    }
}

注册事件订阅者

编写完订阅者后，您就可以准备将其与事件分发器进行注册。您可以使用 Event 外观的 subscribe 方法来注册订阅者。通常，这应该在应用程序的 AppServiceProvider 的 boot 方法中完成：

<?php

namespace App\Providers;

use App\Listeners\UserEventSubscriber;
use Illuminate\Support\Facades\Event;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * 引导任何应用程序服务。
     */
    public function boot(): void
    {
        Event::subscribe(UserEventSubscriber::class);
    }
}

测试

在测试分发事件的代码时，您可能希望指示 Laravel 实际上不执行事件的监听器，因为监听器的代码可以直接且独立于分发相应事件的代码进行测试。当然，要测试监听器本身，您可以实例化一个监听器实例，并在测试中直接调用 handle 方法。

使用 Event 外观的 fake 方法，您可以阻止监听器执行，执行测试中的代码，然后使用 assertDispatched、assertNotDispatched 和 assertNothingDispatched 方法断言您的应用程序分发了哪些事件：

<?php
 
use App\Events\OrderFailedToShip;
use App\Events\OrderShipped;
use Illuminate\Support\Facades\Event;
 
test('订单可以发货', function () {
    Event::fake();
 
    // 执行订单发货...
 
    // 断言一个事件已被分发...
    Event::assertDispatched(OrderShipped::class);
 
    // 断言一个事件被分发了两次...
    Event::assertDispatched(OrderShipped::class, 2);
 
    // 断言一个事件未被分发...
    Event::assertNotDispatched(OrderFailedToShip::class);
 
    // 断言没有事件被分发...
    Event::assertNothingDispatched();
});

<?php
 
namespace Tests\Feature;
 
use App\Events\OrderFailedToShip;
use App\Events\OrderShipped;
use Illuminate\Support\Facades\Event;
use Tests\TestCase;
 
class ExampleTest extends TestCase
{
    /**
     * 测试订单发货。
     */
    public function test_orders_can_be_shipped(): void
    {
        Event::fake();
 
        // 执行订单发货...
 
        // 断言一个事件已被分发...
        Event::assertDispatched(OrderShipped::class);
 
        // 断言一个事件被分发了两次...
        Event::assertDispatched(OrderShipped::class, 2);
 
        // 断言一个事件未被分发...
        Event::assertNotDispatched(OrderFailedToShip::class);
 
        // 断言没有事件被分发...
        Event::assertNothingDispatched();
    }
}

您可以将一个闭包传递给 assertDispatched 或 assertNotDispatched 方法，以断言分发的事件通过给定的“真实性测试”。如果至少有一个事件通过给定的真实性测试被分发，则断言将成功：

Event::assertDispatched(function (OrderShipped $event) use ($order) {
    return $event->order->id === $order->id;
});

如果您只是想断言一个事件监听器正在监听给定的事件，您可以使用 assertListening 方法：

Event::assertListening(
    OrderShipped::class,
    SendShipmentNotification::class
);

[!警告]
调用 Event::fake() 后，将不会执行任何事件监听器。因此，如果您的测试使用依赖于事件的模型工厂，例如在模型的 creating 事件期间创建 UUID，您应该在使用工厂之后调用 Event::fake()。

伪造一部分事件

如果您只想为特定的一组事件伪造事件监听器，您可以将它们传递给 fake 或 fakeFor 方法：

test('订单可以被处理', function () {
    Event::fake([
        OrderCreated::class,
    ]);
 
    $order = Order::factory()->create();
 
    Event::assertDispatched(OrderCreated::class);
 
    // 其他事件按正常方式分发...
    $order->update([...]);
});

/**
 * 测试订单处理。
 */
public function test_orders_can_be_processed(): void
{
    Event::fake([
        OrderCreated::class,
    ]);
 
    $order = Order::factory()->create();
 
    Event::assertDispatched(OrderCreated::class);
 
    // 其他事件按正常方式分发...
    $order->update([...]);
}

您可以使用 except 方法伪造除一组指定事件之外的所有事件：

Event::fake()->except([
    OrderCreated::class,
]);

范围性事件伪造

如果您只想在测试的一部分中伪造事件监听器，您可以使用 fakeFor 方法：

<?php
 
use App\Events\OrderCreated;
use App\Models\Order;
use Illuminate\Support\Facades\Event;
 
test('订单可以被处理', function () {
    $order = Event::fakeFor(function () {
        $order = Order::factory()->create();
 
        Event::assertDispatched(OrderCreated::class);
 
        return $order;
    });
 
    // 事件按正常方式分发且观察者将运行...
    $order->update([...]);
});

<?php
 
namespace Tests\Feature;
 
use App\Events\OrderCreated;
use App\Models\Order;
use Illuminate\Support\Facades\Event;
use Tests\TestCase;
 
class ExampleTest extends TestCase
{
    /**
     * 测试订单处理。
     */
    public function test_orders_can_be_processed(): void
    {
        $order = Event::fakeFor(function () {
            $order = Order::factory()->create();
 
            Event::assertDispatched(OrderCreated::class);
 
            return $order;
        });
 
        // 事件按正常方式分发且观察者将运行...
        $order->update([...]);
    }
}

契约文件存储