# 事件系统
- [简介](#introduction)
- [注册事件和监听器](#registering-events-and-listeners)
- [生成事件和监听器](#generating-events-and-listeners)
- [手动注册事件](#manually-registering-events)
- [事件发现](#event-discovery)
- [定义事件](#defining-events)
- [定义监听器](#defining-listeners)
- [事件监听队列](#queued-event-listeners)
- [手动访问队列](#manually-accessing-the-queue)
- [处理失败任务](#handling-failed-jobs)
- [分发事件](#dispatching-events)
- [事件订阅者](#event-subscribers)
- [编写事件订阅者](#writing-event-subscribers)
- [注册事件订阅者](#registering-event-subscribers)
## 简介
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` 数组来注册的,然而,你也可以在 `EventServiceProvider` 的 `boot` 方法中手动的注册基于闭包的事件:
use App\Events\PodcastProcessed;
/**
* 注册应用的任何其他事件
*
* @return void
*/
public function boot()
{
Event::listen(function (PodcastProcessed $event) {
//
});
}
#### 匿名事件监听器队列
手动注册事件监听器时,可以将监听器的 Closure 闭包放在 `Illuminate\Events\queueable` 函数中,以指示 Laravel 使用 [queue](/docs/laravel/{{version}}/queues) 执行监听器:
use App\Events\PodcastProcessed;
use function Illuminate\Events\queueable;
use Illuminate\Support\Facades\Event;
/**
* 注册应用的任何其他事件
*
* @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) {
// 监听失败的队列...
}));
#### 通配符事件监听器
你可以在注册监听器时使用 `*` 作为通配符参数,这样可以在同一个监听器上捕获多个事件。通配符监听器接收事件名作为其第一个参数,并将整个事件数据数组作为其第二个参数:
Event::listen('event.*', function ($eventName, array $data) {
//
});
### 事件发现
你可以启用自动事件发现,而不是在 `EventServiceProvider` 的 `$listen` 数组中手动的注册事件和监听器。事件发现启用后,Laravel 会通过扫描你应用的 `Listeners`目录来自动的查找和注册事件和监听器。此外,`EventServiceProvider` 中列出的任何明确定义的事件仍将被注册。
Laravel 通过使用反射扫描监听器类来查找事件监听器。 当 Laravel 找到以 `handle` 开头的监听器类方法时,Laravel 会将这些方法注册为方法签名中类型提示的事件的事件监听器:
use App\Events\PodcastProcessed;
class SendPodcastProcessedNotification
{
/**
* 处理给定的事件。
*
* @param \App\Events\PodcastProcessed
* @return void
*/
public function handle(PodcastProcessed $event)
{
//
}
}
事件发现默认情况下是禁用的,但你可以通过覆盖应用程序的 `EventServiceProvider` 的 `shouldDiscoverEvents` 方法来启用它:
/**
* 确定是否应自动发现事件和监听器
*
* @return bool
*/
public function shouldDiscoverEvents()
{
return true;
}
默认情况下,在应用程序的 `Listeners` 目录中的所有监听器将被扫描。如果你想要定义扫描其他目录,可以覆盖 `EventServiceProvider` 中的 `discoverEventsWithin` 方法:
/**
* 获取应该用于发现事件的监听器的目录
*
* @return array
*/
protected function discoverEventsWithin()
{
return [
$this->app->path('Listeners'),
];
}
在生产环境中,你可能不希望框架在每个请求上扫描所有监听器。 因此,在部署过程中,你应该运行 `event:cache` Artisan 命令来缓存应用程序的所有事件和监听器的列表。 框架将使用此列表来加速事件注册过程。`event:clear` 命令则可用于销毁缓存。
> 技巧:`event:list` 命令可用于显示应用程序注册的所有事件和监听器的列表。
## 定义事件
事件类是一个保存与事件相关信息的容器。例如,假设我们生成的 `OrderShipped` 事件接收一个 [Eloquent ORM](/docs/laravel/{{version}}/eloquent) 对象:
order = $order;
}
}
如你所见,这个事件类中没有包含其它逻辑。它只是一个已购买的 `Order` 的实例的容器。如果使用 PHP 的 `serialize` 函数序列化事件对象,事件使用的 `SerializesModels` trait 将会优雅地序列化任何 `Eloquent` 模型。
## 定义监听器
接下来,让我们看一下例子中事件的监听器。事件监听器在 `handle` 方法中接收实例。 `event:generate` 命令会自动加载正确的事件类,并且在 `handle` 方法中加入事件的类型提示。在 `handle` 方法中,你可以执行任何必要的响应事件的操作:
order 来访问订单 ...
}
}
> 技巧:你的事件监听器也可以在构造函数中加入任何依赖关系的类型提示。所有的事件监听器都是通过 Laravel 的 [服务容器](/docs/{{version}}/container) 解析的,因此所有的依赖都将会被自动注入。
#### 停止事件传播
有时,你可以通过在监听器的 `handle` 方法中返回 `false` 来阻止事件被其它的监听器获取。
## 事件监听器队列
如果你的监听器中要执行诸如发送电子邮件或发出 HTTP 请求之类的耗时任务,你可以将任务丢给队列处理。在开始使用队列监听器之前,请确保在你的服务器或者本地开发环境中能够 [配置队列](/docs/{{version}}/queues) 并启动一个队列监听器。
要指定监听器启动队列,你可以在监听器类中实现 `ShouldQueue` 接口。由 Artisan 命令 `event:generate` 生成的监听器已经将此接口导入到当前命名空间中,因此你可以直接使用:
order->subtotal >= 5000;
}
}
### 手动访问队列
如果你需要手动访问监听器下面队列任务的 `delete` 和 `release` 方法,你可以通过使用 `Illuminate\Queue\InteractsWithQueue` trait 来实现。这个 trait 会默认加载到生成的监听器中,并提供对这些方法的访问:
release(30);
}
}
}
### 处理失败任务
有时,你的事件监听器队列可能会失败。如果监听器的队列任务超过了队列中定义的最大尝试次数,则会在监听器上调用 `failed` 方法。 `failed` 方法接收事件实例和导致失败的异常作为参数:
## 分发事件
要分发事件,你可以将事件实例传递给 `event` 辅助函数。该辅助函数将会把事件分发到所有该事件已注册的监听器上。`event` 辅助函数可以全局使用,你可以在应用中的任何位置进行调用:
技巧:在测试时,只需要断言特定事件被分发,而不需要真正地触发监听器。Laravel 的 [内置测试辅助函数](/docs/{{version}}/mocking#event-fake) 可以轻松做到这一点。
## 事件订阅者
### 编写事件订阅者
事件订阅者是可以在自身内部订阅多个事件的类,即能够在单个类中定义多个事件处理器。订阅者应该定义一个 `subscribe` 方法,这个方法接收一个事件分发器实例。你可以调用给定事件分发器上的 `listen` 方法来注册事件监听器:
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` 上的 `$subscribe` 属性来注册订阅者。例如,让我们将 `UserEventSubscriber` 添加到列表中: