# 事件系统
- [简介](#introduction)
- [注册事件 & 监听器](#registering-events-and-listeners)
- [生成事件 & 监听器](#generating-events-and-listeners)
- [手动注册事件](#manually-registering-events)
- [定义事件](#defining-events)
- [定义监听器](#defining-listeners)
- [事件监听器队列](#queued-event-listeners)
- [手动访问队列](#manually-accessing-the-queue)
- [处理失败任务](#handling-failed-jobs)
- [分发事件](#dispatching-events)
- [事件订阅者](#event-subscribers)
- [编写事件订阅者](#writing-event-subscribers)
- [注册事件订阅者](#registering-event-subscribers)
<a name="introduction"></a>
## 事件系统介绍
Laravel 的事件提供了一个简单的观察者实现，能够订阅和监听应用中发生的各种事件。事件类通常存放在 `app/Events` 目录下，而这些事件类的监听器则存放在 `app/Listeners` 目录下。如果在你的应用中你没有看到这些目录，不用担心，它们会在你使用 Artisan 控制台命令生成事件与监听器的时候自动创建。
事件系统为应用各个方面的解耦提供了非常棒的方法，因为单个事件可以拥有多个互不依赖的监听器。举个例子，你可能希望每次订单发货时向用户推送一个 Slack 通知。你可以简单地发起一个可以被监听器接收并转化为 Slack 通知的 `OrderShipped` 事件，而不是将订单处理代码和 Slack 通知代码耦合在一起。
<a name="registering-events-and-listeners"></a>
## 注册事件和监听器
Laravel 应用中的 `EventServiceProvider` 为注册所有的事件监听器提供了一个便利的场所。其中， `listen` 属性包含了所有事件 (键) 以及事件对应的监听器 (值)的数组。当然，你可以根据应用的需要，添加多个事件到 `listen` 属性包含的数组中。举个例子，我们来添加一个 `OrderShipped` 事件：
/**
* 应用程序的事件监听器映射
*
* @var array
*/
protected $listen = [
'App\Events\OrderShipped' => [
'App\Listeners\SendShipmentNotification',
],
];
<a name="generating-events-and-listeners"></a>
### 生成事件 & 监听器
当然，手动创建事件和监听器的文件是件麻烦事。而在这里，你只需要将监听器和事件添加到 `EventServiceProvider` 中，而后使用 `event:generate` 命令。这个命令会生成在 `EventServiceProvider` 中列出的所有事件和监听器。当然，已经存在的事件和监听器将保持不变：
php artisan event:generate
<a name="manually-registering-events"></a>
### 手动注册事件
通常，事件是在 `EventServiceProvider` 的 `$listen` 数组中注册；然而，你也可以在 `EventServiceProvider` 的 `boot` 方法中手动注册基于闭包的这些事件：
/**
* 注册应用中的其它事件
*
* @return void
*/
public function boot()
{
parent::boot();
Event::listen('event.name', function ($foo, $bar) {
//
});
}
#### 通配符事件监听器
你可以在注册监听器时使用 `*` 作为通配符参数，这样可以在同一个监听器上捕获多个事件。通配符监听器接收事件名作为其第一个参数，并将整个事件数据数组作为其第二个参数：
Event::listen('event.*', function ($eventName, array $data) {
//
});
<a name="defining-events"></a>
## 定义事件
事件类是一个保存与事件相关信息的容器。例如，假设我们生成的 `OrderShipped` 事件接收一个 [Eloquent ORM](/docs/{{version}}/eloquent) 对象：
<?php
namespace App\Events;
use App\Order;
use Illuminate\Queue\SerializesModels;
class OrderShipped
{
use SerializesModels;
public $order;
/**
* 创建一个事件实例。
*
* @param \App\Order $order
* @return void
*/
public function __construct(Order $order)
{
$this->order = $order;
}
}
如你所见，这个事件类中没有包含其它逻辑。它只是一个购买的 `Order` 的实例的容器。如果使用 PHP 的 `serialize` 函数序列化事件对象，事件使用的 `SerializesModels` trait 将会优雅地序列化任何 Eloquent 模型。
<a name="defining-listeners"></a>
## 定义监听器
接下来，让我们看一下例子中事件的监听器。事件监听器在 `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 来访问 order ...
}
}
> {tip} 你的事件监听器也可以在构造函数中加入任何依赖关系的类型提示。所有的事件监听器都是通过 Laravel 的 [服务容器](/docs/{{version}}/container) 来解析的，因此所有的依赖都将会被自动注入。
#### 停止事件传播
有时，你可以通过在监听器的 `handle` 方法中返回 `false` 来阻止事件被其它的监听器获取。
<a name="queued-event-listeners"></a>
## 事件监听器队列
如果你的监听器中要执行诸如发送电子邮件或进行 HTTP 请求等比较慢的任务，你可以选择将其丢给队列处理。在开始使用队列监听器之前，请确保在你的服务器或者本地开发环境中能够 [配置队列](/docs/{{version}}/queues) 并启动一个队列监听器。
要指定监听器启动队列，你可以在监听器类中增加 `ShouldQueue` 接口。由 Artisan 命令 `event:generate` 生成的监听器已经将此接口导入到当前命名空间中，因此你可以直接使用：
<?php
namespace App\Listeners;
use App\Events\OrderShipped;
use Illuminate\Contracts\Queue\ShouldQueue;
class SendShipmentNotification implements ShouldQueue
{
//
}
就是这个！当这个监听器被事件调用时，事件调度器会自动使用 Laravel 的 [队列系统](/docs/{{version}}/queues)。如果在队列中执行监听器时没有抛出异常，任务会在执行完成后自动从队列中删除。
#### 自定义队列连接 & 队列名称
如果你想要自定义事件监听器所使用的队列的连接和名称，你可以在监听器类中定义 `$connection`， `$queue` 或 `$delay` 属性：
<?php
namespace App\Listeners;
use App\Events\OrderShipped;
use Illuminate\Contracts\Queue\ShouldQueue;
class SendShipmentNotification implements ShouldQueue
{
/**
* The name of the connection the job should be sent to.
*
* @var string|null
*/
public $connection = 'sqs';
/**
* The name of the queue the job should be sent to.
*
* @var string|null
*/
public $queue = 'listeners';
/**
* The time (seconds) before the job should be processed.
*
* @var int
*/
public $delay = 60;
}
<a name="manually-accessing-the-queue"></a>
### 手动访问队列
如果你需要手动访问监听器下面队列任务的 `delete` 和 `release` 方法，你可以通过使用 `Illuminate\Queue\InteractsWithQueue` trait 来实现。这个 trait 会默认加载到生成的监听器中，并提供对这些方法的访问：
<?php
namespace App\Listeners;
use App\Events\OrderShipped;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Contracts\Queue\ShouldQueue;
class SendShipmentNotification implements ShouldQueue
{
use InteractsWithQueue;
/**
* 处理事件。
*
* @param \App\Events\OrderShipped $event
* @return void
*/
public function handle(OrderShipped $event)
{
if (true) {
$this->release(30);
}
}
}
<a name="handling-failed-jobs"></a>
### 处理失败任务
有时事件监听器的队列任务可能会失败。如果监听器的队列任务超过了队列中定义的最大尝试次数，则会在监听器上调用 `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;
/**
* 处理事件。
*
* @param \App\Events\OrderShipped $event
* @return void
*/
public function handle(OrderShipped $event)
{
//
}
/**
* 处理失败任务。
*
* @param \App\Events\OrderShipped $event
* @param \Exception $exception
* @return void
*/
public function failed(OrderShipped $event, $exception)
{
//
}
}
<a name="dispatching-events"></a>
## 分发事件
如果要分发事件，你可以将事件实例传递给辅助函数 `event` 。该辅助函数将会把事件分发到所有该事件相应的已经注册了的监听器上。 `event` 辅助函数可以全局使用，你可以在应用中的任何位置进行调用：
<?php
namespace App\Http\Controllers;
use App\Order;
use App\Events\OrderShipped;
use App\Http\Controllers\Controller;
class OrderController extends Controller
{
/**
* 将传递过来的订单发货
*
* @param int $orderId
* @return Response
*/
public function ship($orderId)
{
$order = Order::findOrFail($orderId);
// 订单发货逻辑 ...
event(new OrderShipped($order));
}
}
> {tip} 在测试时，只需要断言特定事件被分发，而不需要真正地触发监听器。 Laravel 的 [内置测试辅助函数](/docs/{{version}}/mocking#event-fake) 可以轻松做到这一点。
<a name="event-subscribers"></a>
## 事件订阅者
<a name="writing-event-subscribers"></a>
### 编写事件订阅者
事件订阅者是可以在自身内部订阅多个事件的类，即能够在单个类中定义多个事件处理器。订阅者应该定义一个 `subscribe` 方法，这个方法接收一个事件分发器实例。你可以调用给定事件分发器上的 `listen` 方法来注册事件监听器：
<?php
namespace App\Listeners;
class UserEventSubscriber
{
/**
* 处理用户登录事件。
*/
public function onUserLogin($event) {}
/**
* 处理用户注销事件。
*/
public function onUserLogout($event) {}
/**
* 为订阅者注册监听器
*
* @param \Illuminate\Events\Dispatcher $events
*/
public function subscribe($events)
{
$events->listen(
'Illuminate\Auth\Events\Login',
'App\Listeners\UserEventSubscriber@onUserLogin'
);
$events->listen(
'Illuminate\Auth\Events\Logout',
'App\Listeners\UserEventSubscriber@onUserLogout'
);
}
}
<a name="registering-event-subscribers"></a>
### 注册事件订阅者
在编写完订阅者之后，就可以通过事件分发器对订阅者进行注册。你可以在 `EventServiceProvider` 中的 `$subscribe` 属性中注册订阅者。例如，让我们将 `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',
];
}
- 入门指南
- 安装
- 部署
- 基础功能
- 路由
- 中间件
- CSRF 保护
- 控制器
- 请求
- 响应
- 视图
- URL
- Session
- 表单验证
- 错误
- 日志
- 前端开发
- Blade 模板
- 本地化
- 脚手架
- 编译资源 Mix
- 安全相关
- 用户认证
- API 认证
- 综合话题
- 命令行
- 广播
- 缓存
- 集合
- 事件
- 文件存储
- 辅助函数
- 邮件发送
- 消息通知
- 扩展包开发
- 队列
- 任务调度
- 数据库
- 快速入门
- 查询构造器
- 分页
- 数据库迁移
- 数据填充
- Redis
- Eloquent ORM
- 快速入门
- 速查表
- Artisan
- Auth
- Blade
- Cache
- Collection
- Composer
- Config
- Container
- Cookie
- DB
- Environment
- Event
- File
- Helper
- Input
- Lang
- Log
- Model
- Pagination
- Queue
- Redirect
- Request
- Response
- Route
- SSH
- Schema
- Security
- Session
- Storage
- String
- URL
- UnitTest
- Validation
- View