事件系统

简介

Laravel 的事件提供了一个简单的观察者实现,能够订阅和监听应用中发生的各种事件。事件类保存在 app/Events 目录中,而这些事件的的监听器则被保存在 app/Listeners 目录下。这些目录只有当你使用 Artisan 命令来生成事件和监听器时才会被自动创建。

事件机制是一种很好的应用解耦方式,因为一个事件可以拥有多个互不依赖的监听器。例如,如果你希望每次订单发货时向用户发送一个 Slack 通知。你可以简单地发起一个 OrderShipped 事件,让监听器接收之后转化成一个 Slack 通知,这样你就可以不用把订单的业务代码跟 Slack 通知的代码耦合在一起了。

注册事件和监听器

Laravel 应用中的 EventServiceProvider 有个 listen 数组包含所有的事件(键)以及事件对应的监听器(值)来注册所有的事件监听器,可以灵活地根据需求来添加事件。例如,让我们增加一个 OrderShipped 事件:

  1. /**
  2. * 应用程序的事件监听器映射。
  3. *
  4. * @var array
  5. */
  6. protected $listen = [
  7. 'App\Events\OrderShipped' => [
  8. 'App\Listeners\SendShipmentNotification',
  9. ],
  10. ];

生成事件 & 监听器

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

  1. php artisan event:generate

手动注册事件

事件通常是在 EventServiceProvider 类的 $listen 数组中注册,但是,你也可以在 EventServiceProvider 类的 boot 方法中注册基于事件的闭包:

  1. /**
  2. * 注册应用程序中的任何其它事件。
  3. *
  4. * @return void
  5. */
  6. public function boot()
  7. {
  8. parent::boot();
  9. Event::listen('event.name', function ($foo, $bar) {
  10. //
  11. });
  12. }

通配符事件监听器

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

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

定义事件

事件类其实就只是一个保存与事件相关的信息的数据容器。例如,假设我们生成的 OrderShipped 事件接收一个 Eloquent ORM 对象:

  1. <?php
  2. namespace App\Events;
  3. use App\Order;
  4. use Illuminate\Queue\SerializesModels;
  5. class OrderShipped
  6. {
  7. use SerializesModels;
  8. public $order;
  9. /**
  10. * 创建一个事件实例。
  11. *
  12. * @param Order $order
  13. * @return void
  14. */
  15. public function __construct(Order $order)
  16. {
  17. $this->order = $order;
  18. }
  19. }

正像你看到的那样,这个事件类中没有包含其它逻辑。它只是一个被构建的 Order 对象的容器。如果使用 PHP 的 serialize 函数序列化事件对象,事件使用的 SerializesModels trait 将会优雅地序列化任何 Eloquent 模型。

定义监听器

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

  1. <?php
  2. namespace App\Listeners;
  3. use App\Events\OrderShipped;
  4. class SendShipmentNotification
  5. {
  6. /**
  7. * 创建事件监听器。
  8. *
  9. * @return void
  10. */
  11. public function __construct()
  12. {
  13. //
  14. }
  15. /**
  16. * 处理事件。
  17. *
  18. * @param OrderShipped $event
  19. * @return void
  20. */
  21. public function handle(OrderShipped $event)
  22. {
  23. // 使用 $event->order 来访问 order ...
  24. }
  25. }

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

停止事件传播

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

事件监听器队列

如果你的监听器中要执行诸如发送邮件或者进行 HTTP 请求等比较慢的任务,你可以选择将其交给队列处理。在开始使用监听器队列之前,请确保在你的服务器或本地开发环境中能够配置并启动 队列 监听器。

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

  1. <?php
  2. namespace App\Listeners;
  3. use App\Events\OrderShipped;
  4. use Illuminate\Contracts\Queue\ShouldQueue;
  5. class SendShipmentNotification implements ShouldQueue
  6. {
  7. //
  8. }

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

自定义队列的连接和名称

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

  1. <?php
  2. namespace App\Listeners;
  3. use App\Events\OrderShipped;
  4. use Illuminate\Contracts\Queue\ShouldQueue;
  5. class SendShipmentNotification implements ShouldQueue
  6. {
  7. /**
  8. * 任务应该发送到的队列的连接的名称
  9. *
  10. * @var string|null
  11. */
  12. public $connection = 'sqs';
  13. /**
  14. * 任务应该发送到的队列的名称
  15. *
  16. * @var string|null
  17. */
  18. public $queue = 'listeners';
  19. }

手动访问队列

如果你需要手动访问监听器下面队列任务的 deleterelease 方法,你可以添加 Illuminate\Queue\InteractsWithQueue trait 来实现。这个 trait 会默认加载到生成的监听器中,并提供对这些方法的访问:

  1. <?php
  2. namespace App\Listeners;
  3. use App\Events\OrderShipped;
  4. use Illuminate\Queue\InteractsWithQueue;
  5. use Illuminate\Contracts\Queue\ShouldQueue;
  6. class SendShipmentNotification implements ShouldQueue
  7. {
  8. use InteractsWithQueue;
  9. /**
  10. * 事件处理器
  11. *
  12. * @param \App\Events\OrderShipped $event
  13. * @return void
  14. */
  15. public function handle(OrderShipped $event)
  16. {
  17. if (true) {
  18. $this->release(30);
  19. }
  20. }
  21. }

处理失败任务

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

  1. <?php
  2. namespace App\Listeners;
  3. use App\Events\OrderShipped;
  4. use Illuminate\Queue\InteractsWithQueue;
  5. use Illuminate\Contracts\Queue\ShouldQueue;
  6. class SendShipmentNotification implements ShouldQueue
  7. {
  8. use InteractsWithQueue;
  9. /**
  10. * 事件处理器
  11. *
  12. * @param \App\Events\OrderShipped $event
  13. * @return void
  14. */
  15. public function handle(OrderShipped $event)
  16. {
  17. //
  18. }
  19. /**
  20. * 失败事件处理器
  21. *
  22. * @param \App\Events\OrderShipped $event
  23. * @param \Exception $exception
  24. * @return void
  25. */
  26. public function failed(OrderShipped $event, $exception)
  27. {
  28. //
  29. }
  30. }

分发事件

如果要分发事件,你可以将事件实例传递给辅助函数 event。这个函数将会把事件分发到所有已经注册的监听器上。因为辅助函数 event 是全局可访问的,所以你可以在应用中的任何地方调用它:

  1. <?php
  2. namespace App\Http\Controllers;
  3. use App\Order;
  4. use App\Events\OrderShipped;
  5. use App\Http\Controllers\Controller;
  6. class OrderController extends Controller
  7. {
  8. /**
  9. * 运送给定的订单。
  10. *
  11. * @param int $orderId
  12. * @return Response
  13. */
  14. public function ship($orderId)
  15. {
  16. $order = Order::findOrFail($orderId);
  17. // 订单的发货逻辑...
  18. event(new OrderShipped($order));
  19. }
  20. }

{tip} 在测试时,Laravel 内置的辅助测试函数 能不需要实际触发监听器就能对事件类型断言。

事件订阅者

编写事件订阅者

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

  1. <?php
  2. namespace App\Listeners;
  3. class UserEventSubscriber
  4. {
  5. /**
  6. * 处理用户登录事件。
  7. */
  8. public function onUserLogin($event) {}
  9. /**
  10. * 处理用户注销事件。
  11. */
  12. public function onUserLogout($event) {}
  13. /**
  14. * 为订阅者注册监听器。
  15. *
  16. * @param Illuminate\Events\Dispatcher $events
  17. */
  18. public function subscribe($events)
  19. {
  20. $events->listen(
  21. 'Illuminate\Auth\Events\Login',
  22. 'App\Listeners\UserEventSubscriber@onUserLogin'
  23. );
  24. $events->listen(
  25. 'Illuminate\Auth\Events\Logout',
  26. 'App\Listeners\UserEventSubscriber@onUserLogout'
  27. );
  28. }
  29. }

注册事件订阅者

订阅者写好后,就将其注册到事件分发器中。你可以在 EventServiceProvider 类的 $subscribe 属性中注册订阅者。例如,将 UserEventSubscriber 添加到数组列表中:

  1. <?php
  2. namespace App\Providers;
  3. use Illuminate\Foundation\Support\Providers\EventServiceProvider as ServiceProvider;
  4. class EventServiceProvider extends ServiceProvider
  5. {
  6. /**
  7. * 应用中事件监听器的映射。
  8. *
  9. * @var array
  10. */
  11. protected $listen = [
  12. //
  13. ];
  14. /**
  15. * 需要注册的订阅者类。
  16. *
  17. * @var array
  18. */
  19. protected $subscribe = [
  20. 'App\Listeners\UserEventSubscriber',
  21. ];
  22. }

本文章首发在 LearnKu.com 网站上。

本文中的所有译文仅用于学习和交流目的,转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议,如果我们的工作有侵犯到您的权益,请及时联系我们。