Skip to content

事件

介绍

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

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

生成事件和监听器

要快速生成事件和监听器,你可以使用 make:eventmake:listener Artisan 命令:

shell
php artisan make:event PodcastProcessed

php artisan make:listener SendPodcastNotification --event=PodcastProcessed

为了方便起见,你也可以在没有额外参数的情况下调用 make:eventmake:listener Artisan 命令。当你这样做时,Laravel 会自动提示你输入类名,并在创建监听器时提示你它应该监听的事件:

shell
php artisan make:event

php artisan make:listener

注册事件和监听器

事件发现

默认情况下,Laravel 会通过扫描应用程序的 Listeners 目录自动查找和注册你的事件监听器。当 Laravel 找到任何以 handle__invoke 开头的监听器类方法时,Laravel 会将这些方法注册为事件监听器,事件类型在方法的签名中进行类型提示:

php
use App\Events\PodcastProcessed;

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

你可以使用 PHP 的联合类型监听多个事件:

php
/**
 * 处理给定事件。
 */
public function handle(PodcastProcessed|PodcastPublished $event): void
{
    // ...
}

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

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

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

shell
php artisan event:list

生产环境中的事件发现

为了提高应用程序的速度,你应该使用 optimizeevent:cache Artisan 命令缓存应用程序所有监听器的清单。通常,这个命令应该作为应用程序的 部署过程 的一部分运行。该清单将被框架用于加速事件注册过程。event:clear 命令可用于销毁事件缓存。

手动注册事件

使用 Event facade,你可以在应用程序的 AppServiceProviderboot 方法中手动注册事件及其对应的监听器:

php
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 命令可用于列出应用程序中注册的所有监听器:

shell
php artisan event:list

闭包监听器

通常,监听器被定义为类;然而,你也可以在应用程序的 AppServiceProviderboot 方法中手动注册基于闭包的事件监听器:

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

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

可队列的匿名事件监听器

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

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

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

与队列作业一样,你可以使用 onConnectiononQueuedelay 方法自定义队列监听器的执行:

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

如果你想处理匿名队列监听器的失败,你可以在定义 queueable 监听器时提供一个闭包给 catch 方法。这个闭包将接收事件实例和导致监听器失败的 Throwable 实例:

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

通配符事件监听器

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

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

定义事件

事件类本质上是一个数据容器,保存与事件相关的信息。例如,假设一个 App\Events\OrderShipped 事件接收一个 Eloquent ORM 对象:

php
<?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 实例。事件使用的 SerializesModels 特性将在使用 PHP 的 serialize 函数序列化事件对象时优雅地序列化任何 Eloquent 模型,例如在使用 队列监听器 时。

定义监听器

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

php
<?php

namespace App\Listeners;

use App\Events\OrderShipped;

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

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

你的事件监听器也可以在其构造函数中进行类型提示以获取所需的任何依赖项。所有事件监听器都是通过 Laravel 服务容器 解析的,因此依赖项将自动注入。

停止事件传播

有时,你可能希望停止事件传播到其他监听器。你可以通过在监听器的 handle 方法中返回 false 来实现。

队列事件监听器

队列监听器在你的监听器将执行慢任务(例如发送电子邮件或进行 HTTP 请求)时非常有用。在使用队列监听器之前,请确保 配置你的队列 并在服务器或本地开发环境中启动队列工作者。

要指定监听器应排队,请在监听器类中添加 ShouldQueue 接口。通过 make:listener Artisan 命令生成的监听器已经将此接口导入到当前命名空间中,因此你可以立即使用它:

php
<?php

namespace App\Listeners;

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

class SendShipmentNotification implements ShouldQueue
{
    // ...
}

就是这样!现在,当由此监听器处理的事件被调度时,事件调度器将自动使用 Laravel 的 队列系统 将监听器排队。如果在队列执行监听器时没有抛出异常,则排队作业将在处理完成后自动删除。

自定义队列连接、名称和延迟

如果你想自定义事件监听器的队列连接、队列名称或队列延迟时间,你可以在监听器类上定义 $connection$queue$delay 属性:

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

如果你想在运行时定义监听器的队列连接、队列名称或延迟,可以在监听器上定义 viaConnectionviaQueuewithDelay 方法:

php
/**
 * 获取监听器的队列连接名称。
 */
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
<?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;
    }
}

手动与队列交互

如果你需要手动访问监听器的底层队列作业的 deleterelease 方法,可以使用 Illuminate\Queue\InteractsWithQueue 特性。此特性在生成的监听器中默认导入,并提供对这些方法的访问:

php
<?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
<?php

namespace App\Listeners;

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

class SendShipmentNotification implements ShouldQueueAfterCommit
{
    use InteractsWithQueue;
}
lightbulb

要了解更多关于解决这些问题的信息,请查看有关 队列作业和数据库事务 的文档。

处理失败的作业

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

php
<?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
<?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 实例:

php
use DateTime;

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

指定队列监听器回退

如果你想配置 Laravel 在重试遇到异常的监听器之前等待多少秒,可以在监听器类上定义一个 backoff 属性:

php
/**
 * 在重试队列监听器之前等待的秒数。
 *
 * @var int
 */
public $backoff = 3;

如果你需要更复杂的逻辑来确定监听器的回退时间,可以在监听器类上定义一个 backoff 方法:

php
/**
 * 计算在重试队列监听器之前等待的秒数。
 */
public function backoff(): int
{
    return 3;
}

你可以通过从 backoff 方法返回一个回退值数组来轻松配置“指数”回退。在此示例中,第一次重试的延迟为 1 秒,第二次重试为 5 秒,第三次重试为 10 秒,之后的每次重试如果还有更多尝试,则为 10 秒:

php
/**
 * 计算在重试队列监听器之前等待的秒数。
 *
 * @return array<int, int>
 */
public function backoff(): array
{
    return [1, 5, 10];
}

调度事件

要调度事件,你可以调用事件上的静态 dispatch 方法。此方法由 Illuminate\Foundation\Events\Dispatchable 特性提供。传递给 dispatch 方法的任何参数都将传递给事件的构造函数:

php
<?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');
    }
}

如果你想有条件地调度事件,可以使用 dispatchIfdispatchUnless 方法:

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

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

在测试时,断言某些事件被调度而不实际触发其监听器可能会很有帮助。Laravel 的 内置测试助手 使这变得简单。

在数据库事务后调度事件

有时,你可能希望指示 Laravel 仅在活动数据库事务提交后调度事件。为此,你可以在事件类上实现 ShouldDispatchAfterCommit 接口。

此接口指示 Laravel 在当前数据库事务提交之前不调度事件。如果事务失败,事件将被丢弃。如果在调度事件时没有数据库事务正在进行,事件将立即调度:

php
<?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
<?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
<?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',
        ];
    }
}

注册事件订阅者

编写订阅者后,如果它们遵循 Laravel 的 事件发现约定,Laravel 将自动注册订阅者内的方法。如果没有,你可以使用 Event facade 的 subscribe 方法手动注册你的订阅者。通常,这应该在应用程序的 AppServiceProviderboot 方法中完成:

php
<?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 facade 的 fake 方法,你可以防止监听器执行,执行待测代码,然后使用 assertDispatchedassertNotDispatchedassertNothingDispatched 方法断言你的应用程序调度了哪些事件:

php
<?php

use App\Events\OrderFailedToShip;
use App\Events\OrderShipped;
use Illuminate\Support\Facades\Event;

test('orders can be shipped', function () {
    Event::fake();

    // 执行订单发货...

    // 断言调度了一个事件...
    Event::assertDispatched(OrderShipped::class);

    // 断言一个事件被调度了两次...
    Event::assertDispatched(OrderShipped::class, 2);

    // 断言一个事件没有被调度...
    Event::assertNotDispatched(OrderFailedToShip::class);

    // 断言没有事件被调度...
    Event::assertNothingDispatched();
});
php
<?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();
    }
}

你可以向 assertDispatchedassertNotDispatched 方法传递一个闭包,以断言调度了一个通过给定“真理测试”的事件。如果至少调度了一个通过给定真理测试的事件,则断言将成功:

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

如果你只想断言某个事件监听器正在监听给定事件,可以使用 assertListening 方法:

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

在调用 Event::fake() 后,不会执行任何事件监听器。因此,如果你的测试使用依赖于事件的模型工厂,例如在模型的 creating 事件中创建 UUID,则应在使用工厂 之后 调用 Event::fake()

伪造一部分事件

如果你只想为特定的一组事件伪造事件监听器,可以将它们传递给 fakefakeFor 方法:

php
test('orders can be processed', function () {
    Event::fake([
        OrderCreated::class,
    ]);

    $order = Order::factory()->create();

    Event::assertDispatched(OrderCreated::class);

    // 其他事件正常调度...
    $order->update([...]);
});
php
/**
 * 测试订单处理。
 */
public function test_orders_can_be_processed(): void
{
    Event::fake([
        OrderCreated::class,
    ]);

    $order = Order::factory()->create();

    Event::assertDispatched(OrderCreated::class);

    // 其他事件正常调度...
    $order->update([...]);
}

你可以使用 except 方法伪造所有事件,除了指定的一组事件:

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

作用域事件伪造

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

php
<?php

use App\Events\OrderCreated;
use App\Models\Order;
use Illuminate\Support\Facades\Event;

test('orders can be processed', function () {
    $order = Event::fakeFor(function () {
        $order = Order::factory()->create();

        Event::assertDispatched(OrderCreated::class);

        return $order;
    });

    // 事件正常调度,观察者将运行...
    $order->update([...]);
});
php
<?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([...]);
    }
}