Laravel 9.x 中文文档

简体中文

English

简体中文

English

主题

广播 ​

介绍 ​

在许多现代 Web 应用程序中，WebSockets 用于实现实时、实时更新的用户界面。当服务器上的某些数据更新时，通常会通过 WebSocket 连接发送消息以由客户端处理。WebSockets 提供了一种更高效的替代方案，避免了不断轮询应用程序的服务器以获取应在 UI 中反映的数据更改。

例如，假设您的应用程序能够将用户的数据导出为 CSV 文件并通过电子邮件发送给他们。然而，创建此 CSV 文件需要几分钟时间，因此您选择在队列作业中创建和发送 CSV。当 CSV 已创建并发送给用户时，我们可以使用事件广播来调度 App\Events\UserDataExported 事件，该事件由应用程序的 JavaScript 接收。一旦接收到事件，我们可以向用户显示一条消息，告知他们的 CSV 已通过电子邮件发送给他们，而无需刷新页面。

为了帮助您构建这些类型的功能，Laravel 使得通过 WebSocket 连接“广播”服务器端 Laravel 事件变得容易。广播您的 Laravel 事件允许您在服务器端 Laravel 应用程序和客户端 JavaScript 应用程序之间共享相同的事件名称和数据。

广播的核心概念很简单：客户端在前端连接到命名频道，而您的 Laravel 应用程序在后端向这些频道广播事件。这些事件可以包含您希望提供给前端的任何附加数据。

支持的驱动程序 ​

默认情况下，Laravel 包含两个服务器端广播驱动程序供您选择：Pusher Channels 和 Ably。然而，社区驱动的包如 laravel-websockets 和 soketi 提供了不需要商业广播提供商的额外广播驱动程序。

lightbulb

在深入了解事件广播之前，请确保您已阅读 Laravel 关于事件和监听器的文档。

服务器端安装 ​

要开始使用 Laravel 的事件广播，我们需要在 Laravel 应用程序中进行一些配置，并安装一些包。

事件广播是通过服务器端广播驱动程序完成的，该驱动程序广播您的 Laravel 事件，以便 Laravel Echo（一个 JavaScript 库）可以在浏览器客户端中接收它们。别担心 - 我们将逐步介绍安装过程的每个部分。

配置 ​

所有应用程序的事件广播配置都存储在 config/broadcasting.php 配置文件中。Laravel 开箱即支持几个广播驱动程序：Pusher Channels、Redis 和用于本地开发和调试的 log 驱动程序。此外，还包括一个 null 驱动程序，允许您在测试期间完全禁用广播。config/broadcasting.php 配置文件中包含了每个驱动程序的配置示例。

广播服务提供者 ​

在广播任何事件之前，您首先需要注册 App\Providers\BroadcastServiceProvider。在新的 Laravel 应用程序中，您只需在 config/app.php 配置文件的 providers 数组中取消注释此提供者即可。此 BroadcastServiceProvider 包含注册广播授权路由和回调所需的代码。

队列配置 ​

您还需要配置和运行一个队列工作者。所有事件广播都是通过队列作业完成的，以便应用程序的响应时间不会因事件广播而受到严重影响。

Pusher Channels ​

如果您计划使用 Pusher Channels 广播事件，您应该使用 Composer 包管理器安装 Pusher Channels PHP SDK：

shell
composer require pusher/pusher-php-server

接下来，您应该在 config/broadcasting.php 配置文件中配置您的 Pusher Channels 凭据。此文件中已包含 Pusher Channels 配置示例，允许您快速指定您的密钥、秘密和应用程序 ID。通常，这些值应通过 PUSHER_APP_KEY、PUSHER_APP_SECRET 和 PUSHER_APP_ID 环境变量 设置：

ini
PUSHER_APP_ID=your-pusher-app-id
PUSHER_APP_KEY=your-pusher-key
PUSHER_APP_SECRET=your-pusher-secret
PUSHER_APP_CLUSTER=mt1

config/broadcasting.php 文件的 pusher 配置还允许您指定 Channels 支持的其他 options，例如集群。

接下来，您需要在 .env 文件中将广播驱动程序更改为 pusher：

ini
BROADCAST_DRIVER=pusher

最后，您已准备好安装和配置 Laravel Echo，它将在客户端接收广播事件。

开源 Pusher 替代方案 ​

laravel-websockets 和 soketi 包为 Laravel 提供了 Pusher 兼容的 WebSocket 服务器。这些包允许您在没有商业 WebSocket 提供商的情况下充分利用 Laravel 广播的强大功能。有关安装和使用这些包的更多信息，请查阅我们的开源替代方案文档。

Ably ​

如果您计划使用 Ably 广播事件，您应该使用 Composer 包管理器安装 Ably PHP SDK：

shell
composer require ably/ably-php

接下来，您应该在 config/broadcasting.php 配置文件中配置您的 Ably 凭据。此文件中已包含 Ably 配置示例，允许您快速指定您的密钥。通常，此值应通过 ABLY_KEY 环境变量 设置：

ini
ABLY_KEY=your-ably-key

接下来，您需要在 .env 文件中将广播驱动程序更改为 ably：

ini
BROADCAST_DRIVER=ably

最后，您已准备好安装和配置 Laravel Echo，它将在客户端接收广播事件。

开源替代方案 ​

PHP ​

laravel-websockets 包是一个纯 PHP 的、Pusher 兼容的 Laravel WebSocket 包。此包允许您在没有商业 WebSocket 提供商的情况下充分利用 Laravel 广播的强大功能。有关安装和使用此包的更多信息，请查阅其官方文档。

Node ​

Soketi 是一个基于 Node 的、Pusher 兼容的 Laravel WebSocket 服务器。在底层，Soketi 使用 µWebSockets.js 以实现极高的可扩展性和速度。此包允许您在没有商业 WebSocket 提供商的情况下充分利用 Laravel 广播的强大功能。有关安装和使用此包的更多信息，请查阅其官方文档。

客户端安装 ​

Pusher Channels ​

Laravel Echo 是一个 JavaScript 库，使得订阅频道和监听服务器端广播驱动程序广播的事件变得轻而易举。您可以通过 NPM 包管理器安装 Echo。在此示例中，我们还将安装 pusher-js 包，因为我们将使用 Pusher Channels 广播器：

shell
npm install --save-dev laravel-echo pusher-js

一旦安装了 Echo，您就可以在应用程序的 JavaScript 中创建一个新的 Echo 实例。一个很好的地方是在 Laravel 框架附带的 resources/js/bootstrap.js 文件的底部。默认情况下，此文件中已包含一个 Echo 配置示例 - 您只需取消注释即可：

js
import Echo from 'laravel-echo';
import Pusher from 'pusher-js';

window.Pusher = Pusher;

window.Echo = new Echo({
    broadcaster: 'pusher',
    key: import.meta.env.VITE_PUSHER_APP_KEY,
    cluster: import.meta.env.VITE_PUSHER_APP_CLUSTER,
    forceTLS: true
});

一旦您取消注释并根据需要调整了 Echo 配置，您可以编译应用程序的资产：

shell
npm run dev
lightbulb

要了解有关编译应用程序 JavaScript 资产的更多信息，请查阅 Vite 文档。

使用现有客户端实例 ​

如果您已经有一个预配置的 Pusher Channels 客户端实例，并希望 Echo 使用它，您可以通过 client 配置选项将其传递给 Echo：

js
import Echo from 'laravel-echo';
import Pusher from 'pusher-js';

const options = {
    broadcaster: 'pusher',
    key: 'your-pusher-channels-key'
}

window.Echo = new Echo({
    ...options,
    client: new Pusher(options.key, options)
});

Ably ​

Laravel Echo 是一个 JavaScript 库，使得订阅频道和监听服务器端广播驱动程序广播的事件变得轻而易举。您可以通过 NPM 包管理器安装 Echo。在此示例中，我们还将安装 pusher-js 包。

您可能会想知道为什么我们会安装 pusher-js JavaScript 库，即使我们使用 Ably 广播事件。幸运的是，Ably 包含一个 Pusher 兼容模式，使我们能够在客户端应用程序中使用 Pusher 协议监听事件：

shell
npm install --save-dev laravel-echo pusher-js

在继续之前，您应该在 Ably 应用程序设置中启用 Pusher 协议支持。您可以在 Ably 应用程序设置仪表板的“协议适配器设置”部分启用此功能。

一旦安装了 Echo，您就可以在应用程序的 JavaScript 中创建一个新的 Echo 实例。一个很好的地方是在 Laravel 框架附带的 resources/js/bootstrap.js 文件的底部。默认情况下，此文件中的 Echo 配置示例是为 Pusher 设计的。您可以复制下面的配置以将配置转换为 Ably：

js
import Echo from 'laravel-echo';
import Pusher from 'pusher-js';

window.Pusher = Pusher;

window.Echo = new Echo({
    broadcaster: 'pusher',
    key: import.meta.env.VITE_ABLY_PUBLIC_KEY,
    wsHost: 'realtime-pusher.ably.io',
    wsPort: 443,
    disableStats: true,
    encrypted: true,
});

请注意，我们的 Ably Echo 配置引用了一个 VITE_ABLY_PUBLIC_KEY 环境变量。此变量的值应为您的 Ably 公钥。您的公钥是 Ably 密钥中 : 字符之前的部分。

一旦您取消注释并根据需要调整了 Echo 配置，您可以编译应用程序的资产：

shell
npm run dev
lightbulb

要了解有关编译应用程序 JavaScript 资产的更多信息，请查阅 Vite 文档。

概念概述 ​

Laravel 的事件广播允许您使用基于驱动程序的方法通过 WebSockets 将服务器端 Laravel 事件广播到客户端 JavaScript 应用程序。目前，Laravel 附带 Pusher Channels 和 Ably 驱动程序。事件可以使用 Laravel Echo JavaScript 包轻松地在客户端上消费。

事件通过“频道”广播，这些频道可以指定为公共或私有。应用程序的任何访问者都可以在没有任何身份验证或授权的情况下订阅公共频道；然而，为了订阅私有频道，用户必须经过身份验证并被授权收听该频道。

lightbulb

如果您想探索 Pusher 的开源替代方案，请查看开源替代方案。

使用示例应用程序 ​

在深入了解事件广播的每个组件之前，让我们通过一个电子商务商店的示例进行高层次概述。

在我们的应用程序中，假设我们有一个页面允许用户查看其订单的运输状态。假设当应用程序处理运输状态更新时，会触发一个 OrderShipmentStatusUpdated 事件：

php
use App\Events\OrderShipmentStatusUpdated;

OrderShipmentStatusUpdated::dispatch($order);

ShouldBroadcast 接口 ​

当用户查看其订单之一时，我们不希望他们必须刷新页面以查看状态更新。相反，我们希望在创建更新时将其广播到应用程序。因此，我们需要使用 ShouldBroadcast 接口标记 OrderShipmentStatusUpdated 事件。这将指示 Laravel 在事件触发时广播事件：

php
<?php

namespace App\Events;

use App\Models\Order;
use Illuminate\Broadcasting\Channel;
use Illuminate\Broadcasting\InteractsWithSockets;
use Illuminate\Broadcasting\PresenceChannel;
use Illuminate\Broadcasting\PrivateChannel;
use Illuminate\Contracts\Broadcasting\ShouldBroadcast;
use Illuminate\Queue\SerializesModels;

class OrderShipmentStatusUpdated implements ShouldBroadcast
{
    /**
     * 订单实例。
     *
     * @var \App\Order
     */
    public $order;
}

ShouldBroadcast 接口要求我们的事件定义一个 broadcastOn 方法。此方法负责返回事件应广播的频道。生成的事件类上已经定义了此方法的空存根，因此我们只需填写其详细信息。我们只希望订单的创建者能够查看状态更新，因此我们将在与订单相关的私有频道上广播事件：

php
/**
 * 获取事件应广播的频道。
 *
 * @return \Illuminate\Broadcasting\PrivateChannel
 */
public function broadcastOn()
{
    return new PrivateChannel('orders.'.$this->order->id);
}

授权频道 ​

请记住，用户必须被授权才能收听私有频道。我们可以在应用程序的 routes/channels.php 文件中定义我们的频道授权规则。在此示例中，我们需要验证任何尝试收听私有 orders.1 频道的用户是否确实是订单的创建者：

php
use App\Models\Order;

Broadcast::channel('orders.{orderId}', function ($user, $orderId) {
    return $user->id === Order::findOrNew($orderId)->user_id;
});

channel 方法接受两个参数：频道的名称和一个回调，该回调返回 true 或 false，指示用户是否被授权收听该频道。

所有授权回调都接收当前经过身份验证的用户作为第一个参数，任何其他通配符参数作为后续参数。在此示例中，我们使用 {orderId} 占位符来指示频道名称的“ID”部分是一个通配符。

监听事件广播 ​

接下来，剩下的就是在我们的 JavaScript 应用程序中监听事件。我们可以使用 Laravel Echo 来做到这一点。首先，我们将使用 private 方法订阅私有频道。然后，我们可以使用 listen 方法监听 OrderShipmentStatusUpdated 事件。默认情况下，事件的所有公共属性都将包含在广播事件中：

js
Echo.private(`orders.${orderId}`)
    .listen('OrderShipmentStatusUpdated', (e) => {
        console.log(e.order);
    });

定义广播事件 ​

要通知 Laravel 某个事件应被广播，您必须在事件类上实现 Illuminate\Contracts\Broadcasting\ShouldBroadcast 接口。此接口已导入到框架生成的所有事件类中，因此您可以轻松地将其添加到任何事件中。

ShouldBroadcast 接口要求您实现一个方法：broadcastOn。broadcastOn 方法应返回事件应广播的频道或频道数组。频道应为 Channel、PrivateChannel 或 PresenceChannel 的实例。Channel 的实例表示任何用户都可以订阅的公共频道，而 PrivateChannels 和 PresenceChannels 表示需要频道授权的私有频道：

php
<?php

namespace App\Events;

use App\Models\User;
use Illuminate\Broadcasting\Channel;
use Illuminate\Broadcasting\InteractsWithSockets;
use Illuminate\Broadcasting\PresenceChannel;
use Illuminate\Broadcasting\PrivateChannel;
use Illuminate\Contracts\Broadcasting\ShouldBroadcast;
use Illuminate\Queue\SerializesModels;

class ServerCreated implements ShouldBroadcast
{
    use SerializesModels;

    /**
     * 创建服务器的用户。
     *
     * @var \App\Models\User
     */
    public $user;

    /**
     * 创建一个新的事件实例。
     *
     * @param  \App\Models\User  $user
     * @return void
     */
    public function __construct(User $user)
    {
        $this->user = $user;
    }

    /**
     * 获取事件应广播的频道。
     *
     * @return Channel|array
     */
    public function broadcastOn()
    {
        return new PrivateChannel('user.'.$this->user->id);
    }
}

在实现 ShouldBroadcast 接口后，您只需像往常一样触发事件。一旦事件被触发，队列作业将自动使用您指定的广播驱动程序广播事件。

广播名称 ​

默认情况下，Laravel 将使用事件的类名广播事件。然而，您可以通过在事件上定义 broadcastAs 方法来自定义广播名称：

php
/**
 * 事件的广播名称。
 *
 * @return string
 */
public function broadcastAs()
{
    return 'server.created';
}

如果您使用 broadcastAs 方法自定义广播名称，您应确保以 . 字符开头注册监听器。这将指示 Echo 不要将应用程序的命名空间添加到事件中：

php
.listen('.server.created', function (e) {
    ....
});

广播数据 ​

当事件被广播时，其所有 public 属性将自动序列化并作为事件的有效负载广播，允许您从 JavaScript 应用程序访问其任何公共数据。因此，例如，如果您的事件有一个包含 Eloquent 模型的公共 $user 属性，事件的广播有效负载将是：

json
{
    "user": {
        "id": 1,
        "name": "Patrick Stewart"
        ...
    }
}

然而，如果您希望对广播有效负载进行更细粒度的控制，您可以向事件添加一个 broadcastWith 方法。此方法应返回您希望作为事件有效负载广播的数据数组：

php
/**
 * 获取要广播的数据。
 *
 * @return array
 */
public function broadcastWith()
{
    return ['id' => $this->user->id];
}

广播队列 ​

默认情况下，每个广播事件都放置在 queue.php 配置文件中指定的默认队列连接的默认队列上。您可以通过在事件类上定义 connection 和 queue 属性来自定义广播器使用的队列连接和名称：

php
/**
 * 广播事件时要使用的队列连接的名称。
 *
 * @var string
 */
public $connection = 'redis';

/**
 * 要放置广播作业的队列的名称。
 *
 * @var string
 */
public $queue = 'default';

或者，您可以通过在事件上定义 broadcastQueue 方法来自定义队列名称：

php
/**
 * 要放置广播作业的队列的名称。
 *
 * @return string
 */
public function broadcastQueue()
{
    return 'default';
}

如果您希望使用 sync 队列而不是默认队列驱动程序广播事件，您可以实现 ShouldBroadcastNow 接口而不是 ShouldBroadcast：

php
<?php

use Illuminate\Contracts\Broadcasting\ShouldBroadcastNow;

class OrderShipmentStatusUpdated implements ShouldBroadcastNow
{
    //
}

广播条件 ​

有时您希望仅在给定条件为真时广播事件。您可以通过在事件类上添加 broadcastWhen 方法来定义这些条件：

php
/**
 * 确定此事件是否应广播。
 *
 * @return bool
 */
public function broadcastWhen()
{
    return $this->order->value > 100;
}

广播与数据库事务 ​

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

如果您的队列连接的 after_commit 配置选项设置为 false，您仍然可以通过在事件类上定义 $afterCommit 属性来指示特定广播事件应在所有打开的数据库事务提交后调度：

php
<?php

namespace App\Events;

use Illuminate\Contracts\Broadcasting\ShouldBroadcast;
use Illuminate\Queue\SerializesModels;

class ServerCreated implements ShouldBroadcast
{
    use SerializesModels;

    public $afterCommit = true;
}
lightbulb

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

授权频道 ​

私有频道要求您授权当前经过身份验证的用户是否可以实际收听该频道。这是通过向您的 Laravel 应用程序发送带有频道名称的 HTTP 请求来完成的，并允许您的应用程序确定用户是否可以收听该频道。当使用 Laravel Echo 时，授权订阅私有频道的 HTTP 请求将自动发出；然而，您需要定义适当的路由来响应这些请求。

定义授权路由 ​

幸运的是，Laravel 使得定义响应频道授权请求的路由变得容易。在您的 Laravel 应用程序中包含的 App\Providers\BroadcastServiceProvider 中，您将看到对 Broadcast::routes 方法的调用。此方法将注册 /broadcasting/auth 路由以处理授权请求：

php
Broadcast::routes();

Broadcast::routes 方法将自动将其路由放置在 web 中间件组中；然而，如果您希望自定义分配的属性，您可以将属性数组传递给该方法：

php
Broadcast::routes($attributes);

自定义授权端点 ​

默认情况下，Echo 将使用 /broadcasting/auth 端点来授权频道访问。然而，您可以通过将 authEndpoint 配置选项传递给 Echo 实例来自定义授权端点：

js
window.Echo = new Echo({
    broadcaster: 'pusher',
    // ...
    authEndpoint: '/custom/endpoint/auth'
});

自定义授权请求 ​

您可以通过在初始化 Echo 时提供自定义授权器来自定义 Laravel Echo 如何执行授权请求：

js
window.Echo = new Echo({
    // ...
    authorizer: (channel, options) => {
        return {
            authorize: (socketId, callback) => {
                axios.post('/api/broadcasting/auth', {
                    socket_id: socketId,
                    channel_name: channel.name
                })
                .then(response => {
                    callback(null, response.data);
                })
                .catch(error => {
                    callback(error);
                });
            }
        };
    },
})

定义授权回调 ​

接下来，我们需要定义实际确定当前经过身份验证的用户是否可以收听给定频道的逻辑。这是在应用程序附带的 routes/channels.php 文件中完成的。在此文件中，您可以使用 Broadcast::channel 方法注册频道授权回调：

php
Broadcast::channel('orders.{orderId}', function ($user, $orderId) {
    return $user->id === Order::findOrNew($orderId)->user_id;
});

channel 方法接受两个参数：频道的名称和一个回调，该回调返回 true 或 false，指示用户是否被授权收听该频道。

所有授权回调都接收当前经过身份验证的用户作为第一个参数，任何其他通配符参数作为后续参数。在此示例中，我们使用 {orderId} 占位符来指示频道名称的“ID”部分是一个通配符。

授权回调模型绑定 ​

就像 HTTP 路由一样，频道路由也可以利用隐式和显式路由模型绑定。例如，您可以请求一个实际的 Order 模型实例，而不是接收字符串或数字订单 ID：

php
use App\Models\Order;

Broadcast::channel('orders.{order}', function ($user, Order $order) {
    return $user->id === $order->user_id;
});
exclamation

与 HTTP 路由模型绑定不同，频道模型绑定不支持自动隐式模型绑定作用域。然而，这很少是一个问题，因为大多数频道可以基于单个模型的唯一主键进行作用域。

授权回调身份验证 ​

私有和存在广播频道通过应用程序的默认身份验证守卫对当前用户进行身份验证。如果用户未经过身份验证，频道授权将自动被拒绝，并且授权回调永远不会执行。然而，如果需要，您可以分配多个自定义守卫来验证传入请求：

php
Broadcast::channel('channel', function () {
    // ...
}, ['guards' => ['web', 'admin']]);

定义频道类 ​

如果您的应用程序正在消费许多不同的频道，您的 routes/channels.php 文件可能会变得庞大。因此，您可以使用频道类而不是使用闭包来授权频道。要生成频道类，请使用 make:channel Artisan 命令。此命令将在 App/Broadcasting 目录中放置一个新的频道类。

shell
php artisan make:channel OrderChannel

接下来，在 routes/channels.php 文件中注册您的频道：

php
use App\Broadcasting\OrderChannel;

Broadcast::channel('orders.{order}', OrderChannel::class);

最后，您可以将频道的授权逻辑放在频道类的 join 方法中。此 join 方法将包含您通常放置在频道授权闭包中的逻辑。您还可以利用频道模型绑定：

php
<?php

namespace App\Broadcasting;

use App\Models\Order;
use App\Models\User;

class OrderChannel
{
    /**
     * 创建一个新的频道实例。
     *
     * @return void
     */
    public function __construct()
    {
        //
    }

    /**
     * 验证用户对频道的访问。
     *
     * @param  \App\Models\User  $user
     * @param  \App\Models\Order  $order
     * @return array|bool
     */
    public function join(User $user, Order $order)
    {
        return $user->id === $order->user_id;
    }
}
lightbulb

像 Laravel 中的许多其他类一样，频道类将自动由服务容器解析。因此，您可以在其构造函数中类型提示频道所需的任何依赖项。

广播事件 ​

一旦您定义了一个事件并使用 ShouldBroadcast 接口标记它，您只需使用事件的调度方法触发事件。事件调度器将注意到事件已标记为 ShouldBroadcast 接口，并将事件排队以进行广播：

php
use App\Events\OrderShipmentStatusUpdated;

OrderShipmentStatusUpdated::dispatch($order);

仅对其他人 ​

在构建使用事件广播的应用程序时，您可能偶尔需要将事件广播到给定频道的所有订阅者，除了当前用户。您可以使用 broadcast 助手和 toOthers 方法来实现这一点：

php
use App\Events\OrderShipmentStatusUpdated;

broadcast(new OrderShipmentStatusUpdated($update))->toOthers();

为了更好地理解何时可能需要使用 toOthers 方法，让我们想象一个任务列表应用程序，其中用户可以通过输入任务名称来创建新任务。要创建任务，您的应用程序可能会向 /task URL 发出请求，该请求广播任务的创建并返回新任务的 JSON 表示。当您的 JavaScript 应用程序从端点接收到响应时，它可能会直接将新任务插入到其任务列表中，如下所示：

js
axios.post('/task', task)
    .then((response) => {
        this.tasks.push(response.data);
    });

然而，请记住，我们还广播了任务的创建。如果您的 JavaScript 应用程序也在监听此事件以将任务添加到任务列表中，您将有重复的任务：一个来自端点，一个来自广播。您可以通过使用 toOthers 方法来解决此问题，以指示广播器不向当前用户广播事件。

exclamation

您的事件必须使用 Illuminate\Broadcasting\InteractsWithSockets 特性才能调用 toOthers 方法。

配置 ​

当您初始化 Laravel Echo 实例时，会为连接分配一个 socket ID。如果您使用全局 Axios 实例从 JavaScript 应用程序发出 HTTP 请求，socket ID 将自动附加到每个传出请求作为 X-Socket-ID 头。然后，当您调用 toOthers 方法时，Laravel 将从头中提取 socket ID，并指示广播器不向具有该 socket ID 的任何连接广播。

如果您没有使用全局 Axios 实例，您将需要手动配置 JavaScript 应用程序以在所有传出请求中发送 X-Socket-ID 头。您可以使用 Echo.socketId 方法检索 socket ID：

js
var socketId = Echo.socketId();

自定义连接 ​

如果您的应用程序与多个广播连接交互，并且您希望使用非默认的广播器广播事件，您可以使用 via 方法指定要推送事件的连接：

php
use App\Events\OrderShipmentStatusUpdated;

broadcast(new OrderShipmentStatusUpdated($update))->via('pusher');

或者，您可以通过在事件的构造函数中调用 broadcastVia 方法来指定事件的广播连接。然而，在这样做之前，您应确保事件类使用 InteractsWithBroadcasting 特性：

php
<?php

namespace App\Events;

use Illuminate\Broadcasting\Channel;
use Illuminate\Broadcasting\InteractsWithBroadcasting;
use Illuminate\Broadcasting\InteractsWithSockets;
use Illuminate\Broadcasting\PresenceChannel;
use Illuminate\Broadcasting\PrivateChannel;
use Illuminate\Contracts\Broadcasting\ShouldBroadcast;
use Illuminate\Queue\SerializesModels;

class OrderShipmentStatusUpdated implements ShouldBroadcast
{
    use InteractsWithBroadcasting;

    /**
     * 创建一个新的事件实例。
     *
     * @return void
     */
    public function __construct()
    {
        $this->broadcastVia('pusher');
    }
}

接收广播 ​

监听事件 ​

一旦您安装并实例化 Laravel Echo，您就可以开始监听从 Laravel 应用程序广播的事件。首先，使用 channel 方法获取频道的实例，然后调用 listen 方法监听指定的事件：

js
Echo.channel(`orders.${this.order.id}`)
    .listen('OrderShipmentStatusUpdated', (e) => {
        console.log(e.order.name);
    });

如果您希望在私有频道上监听事件，请使用 private 方法。您可以继续链式调用 listen 方法，以在单个频道上监听多个事件：

js
Echo.private(`orders.${this.order.id}`)
    .listen(/* ... */)
    .listen(/* ... */)
    .listen(/* ... */);

停止监听事件 ​

如果您希望停止监听给定事件而不离开频道，您可以使用 stopListening 方法：

js
Echo.private(`orders.${this.order.id}`)
    .stopListening('OrderShipmentStatusUpdated')

离开频道 ​

要离开频道，您可以在 Echo 实例上调用 leaveChannel 方法：

js
Echo.leaveChannel(`orders.${this.order.id}`);

如果您希望离开频道及其关联的私有和存在频道，您可以调用 leave 方法：

js
Echo.leave(`orders.${this.order.id}`);

命名空间 ​

您可能已经注意到，在上面的示例中，我们没有为事件类指定完整的 App\Events 命名空间。这是因为 Echo 将自动假定事件位于 App\Events 命名空间中。然而，您可以在实例化 Echo 时通过传递 namespace 配置选项来配置根命名空间：

js
window.Echo = new Echo({
    broadcaster: 'pusher',
    // ...
    namespace: 'App.Other.Namespace'
});

或者，您可以在使用 Echo 订阅事件时为事件类添加 . 前缀。这将允许您始终指定完全限定的类名：

js
Echo.channel('orders')
    .listen('.Namespace\\Event\\Class', (e) => {
        //
    });

存在频道 ​

存在频道建立在私有频道的安全性之上，同时提供了了解谁订阅了频道的附加功能。这使得构建强大的协作应用程序功能变得容易，例如在另一个用户查看同一页面时通知用户或列出聊天室的成员。

授权存在频道 ​

所有存在频道也是私有频道；因此，用户必须被授权访问它们。然而，在为存在频道定义授权回调时，您不应返回 true，即用户被授权加入频道。相反，您应该返回有关用户的数据数组。

授权回调返回的数据将在 JavaScript 应用程序中的存在频道事件监听器中可用。如果用户未被授权加入存在频道，您应返回 false 或 null：

php
Broadcast::channel('chat.{roomId}', function ($user, $roomId) {
    if ($user->canJoinRoom($roomId)) {
        return ['id' => $user->id, 'name' => $user->name];
    }
});

加入存在频道 ​

要加入存在频道，您可以使用 Echo 的 join 方法。join 方法将返回一个 PresenceChannel 实现，该实现除了暴露 listen 方法外，还允许您订阅 here、joining 和 leaving 事件。

js
Echo.join(`chat.${roomId}`)
    .here((users) => {
        //
    })
    .joining((user) => {
        console.log(user.name);
    })
    .leaving((user) => {
        console.log(user.name);
    })
    .error((error) => {
        console.error(error);
    });

here 回调将在频道成功加入后立即执行，并将接收一个包含所有其他用户信息的数组，这些用户当前订阅了频道。joining 方法将在新用户加入频道时执行，而 leaving 方法将在用户离开频道时执行。error 方法将在身份验证端点返回 HTTP 状态码不是 200 或解析返回的 JSON 时出现问题时执行。

广播到存在频道 ​

存在频道可以像公共或私有频道一样接收事件。以聊天室为例，我们可能希望将 NewMessage 事件广播到房间的存在频道。为此，我们将从事件的 broadcastOn 方法返回一个 PresenceChannel 实例：

php
/**
 * 获取事件应广播的频道。
 *
 * @return Channel|array
 */
public function broadcastOn()
{
    return new PresenceChannel('room.'.$this->message->room_id);
}

与其他事件一样，您可以使用 broadcast 助手和 toOthers 方法将当前用户排除在接收广播之外：

php
broadcast(new NewMessage($message));

broadcast(new NewMessage($message))->toOthers();

与其他类型的事件一样，您可以使用 Echo 的 listen 方法监听发送到存在频道的事件：

js
Echo.join(`chat.${roomId}`)
    .here(/* ... */)
    .joining(/* ... */)
    .leaving(/* ... */)
    .listen('NewMessage', (e) => {
        //
    });

模型广播 ​

exclamation

在阅读以下有关模型广播的文档之前，我们建议您熟悉 Laravel 的模型广播服务的一般概念以及如何手动创建和监听广播事件。

在应用程序的 Eloquent 模型 创建、更新或删除时，通常会广播事件。当然，这可以通过手动为 Eloquent 模型状态更改定义自定义事件并将这些事件标记为 ShouldBroadcast 接口来轻松实现。

然而，如果您在应用程序中不将这些事件用于任何其他目的，仅仅为了广播它们而创建事件类可能会很麻烦。为了解决这个问题，Laravel 允许您指示 Eloquent 模型应自动广播其状态更改。

要开始，您的 Eloquent 模型应使用 Illuminate\Database\Eloquent\BroadcastsEvents 特性。此外，模型应定义一个 broadcastOn 方法，该方法将返回模型事件应广播的频道数组：

php
<?php

namespace App\Models;

use Illuminate\Broadcasting\PrivateChannel;
use Illuminate\Database\Eloquent\BroadcastsEvents;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    use BroadcastsEvents, HasFactory;

    /**
     * 获取帖子所属的用户。
     */
    public function user()
    {
        return $this->belongsTo(User::class);
    }

    /**
     * 获取模型事件应广播的频道。
     *
     * @param  string  $event
     * @return \Illuminate\Broadcasting\Channel|array
     */
    public function broadcastOn($event)
    {
        return [$this, $this->user];
    }
}

一旦您的模型包含此特性并定义其广播频道，它将在创建、更新、删除、删除或恢复模型实例时自动广播事件。

此外，您可能已经注意到 broadcastOn 方法接收一个字符串 $event 参数。此参数包含模型上发生的事件类型，并将具有 created、updated、deleted、trashed 或 restored 的值。通过检查此变量的值，您可以确定模型应为特定事件广播到哪些频道（如果有的话）：

php
/**
 * 获取模型事件应广播的频道。
 *
 * @param  string  $event
 * @return \Illuminate\Broadcasting\Channel|array
 */
public function broadcastOn($event)
{
    return match ($event) {
        'deleted' => [],
        default => [$this, $this->user],
    };
}

自定义模型广播事件创建 ​

有时，您可能希望自定义 Laravel 如何创建底层模型广播事件。您可以通过在 Eloquent 模型上定义 newBroadcastableEvent 方法来实现这一点。此方法应返回一个 Illuminate\Database\Eloquent\BroadcastableModelEventOccurred 实例：

php
use Illuminate\Database\Eloquent\BroadcastableModelEventOccurred;

/**
 * 为模型创建一个新的可广播模型事件。
 *
 * @param  string  $event
 * @return \Illuminate\Database\Eloquent\BroadcastableModelEventOccurred
 */
protected function newBroadcastableEvent($event)
{
    return (new BroadcastableModelEventOccurred(
        $this, $event
    ))->dontBroadcastToCurrentUser();
}

模型广播约定 ​

频道约定 ​

正如您可能已经注意到的，模型示例中的 broadcastOn 方法没有返回 Channel 实例。相反，直接返回了 Eloquent 模型。如果您的模型的 broadcastOn 方法返回 Eloquent 模型实例（或方法返回的数组中包含模型实例），Laravel 将自动为模型实例化一个私有频道实例，使用模型的类名和主键标识符作为频道名称。

因此，App\Models\User 模型的 id 为 1 将被转换为名称为 App.Models.User.1 的 Illuminate\Broadcasting\PrivateChannel 实例。当然，除了从模型的 broadcastOn 方法返回 Eloquent 模型实例外，您还可以返回完整的 Channel 实例，以便完全控制模型的频道名称：

php
use Illuminate\Broadcasting\PrivateChannel;

/**
 * 获取模型事件应广播的频道。
 *
 * @param  string  $event
 * @return \Illuminate\Broadcasting\Channel|array
 */
public function broadcastOn($event)
{
    return [new PrivateChannel('user.'.$this->id)];
}

如果您计划从模型的 broadcastOn 方法显式返回频道实例，您可以将 Eloquent 模型实例传递给频道的构造函数。这样做时，Laravel 将使用上面讨论的模型频道约定将 Eloquent 模型转换为频道名称字符串：

php
return [new Channel($this->user)];

如果您需要确定模型的频道名称，您可以在任何模型实例上调用 broadcastChannel 方法。例如，此方法为 App\Models\User 模型的 id 为 1 返回字符串 App.Models.User.1：

php
$user->broadcastChannel()

事件约定 ​

由于模型广播事件不与应用程序的 App\Events 目录中的“实际”事件相关联，因此它们根据约定分配名称和有效负载。Laravel 的约定是使用模型的类名（不包括命名空间）和触发广播的模型事件名称广播事件。

因此，例如，对 App\Models\Post 模型的更新将向客户端应用程序广播一个名为 PostUpdated 的事件，并具有以下有效负载：

json
{
    "model": {
        "id": 1,
        "title": "My first post"
        ...
    },
    ...
    "socket": "someSocketId",
}

删除 App\Models\User 模型将广播一个名为 UserDeleted 的事件。

如果您愿意，您可以通过向模型添加 broadcastAs 和 broadcastWith 方法来自定义广播名称和有效负载。这些方法接收正在发生的模型事件/操作的名称，允许您为每个模型操作自定义事件的名称和有效负载。如果 broadcastAs 方法返回 null，Laravel 将在广播事件时使用上面讨论的模型广播事件名称约定：

php
/**
 * 模型事件的广播名称。
 *
 * @param  string  $event
 * @return string|null
 */
public function broadcastAs($event)
{
    return match ($event) {
        'created' => 'post.created',
        default => null,
    };
}

/**
 * 获取模型的广播数据。
 *
 * @param  string  $event
 * @return array
 */
public function broadcastWith($event)
{
    return match ($event) {
        'created' => ['title' => $this->title],
        default => ['model' => $this],
    };
}

监听模型广播 ​

一旦您将 BroadcastsEvents 特性添加到模型并定义了模型的 broadcastOn 方法，您就可以在客户端应用程序中开始监听广播的模型事件。在开始之前，您可能希望查阅有关监听事件的完整文档。

首先，使用 private 方法获取频道的实例，然后调用 listen 方法监听指定的事件。通常，传递给 private 方法的频道名称应与 Laravel 的模型广播约定相对应。

一旦您获得了频道实例，您可以使用 listen 方法监听特定事件。由于模型广播事件不与应用程序的 App\Events 目录中的“实际”事件相关联，事件名称必须以 . 为前缀，以指示它不属于特定命名空间。每个模型广播事件都有一个 model 属性，其中包含模型的所有可广播属性：

js
Echo.private(`App.Models.User.${this.user.id}`)
    .listen('.PostUpdated', (e) => {
        console.log(e.model);
    });

客户端事件 ​

lightbulb

使用 Pusher Channels 时，您必须在应用程序仪表板的“应用程序设置”部分中启用“客户端事件”选项，以便发送客户端事件。

有时，您可能希望在不访问 Laravel 应用程序的情况下将事件广播到其他连接的客户端。这对于诸如“正在输入”通知之类的事情特别有用，您希望在给定屏幕上向应用程序的用户发出警告，告知另一个用户正在输入消息。

要广播客户端事件，您可以使用 Echo 的 whisper 方法：

js
Echo.private(`chat.${roomId}`)
    .whisper('typing', {
        name: this.user.name
    });

要监听客户端事件，您可以使用 listenForWhisper 方法：

js
Echo.private(`chat.${roomId}`)
    .listenForWhisper('typing', (e) => {
        console.log(e.name);
    });

通知 ​

通过将事件广播与通知配对，您的 JavaScript 应用程序可以在不需要刷新页面的情况下接收新通知。在开始之前，请务必阅读有关使用广播通知频道的文档。

一旦您配置了使用广播频道的通知，您可以使用 Echo 的 notification 方法监听广播事件。请记住，频道名称应与接收通知的实体的类名匹配：

js
Echo.private(`App.Models.User.${userId}`)
    .notification((notification) => {
        console.log(notification.type);
    });

在此示例中，通过 broadcast 频道发送到 App\Models\User 实例的所有通知都将由回调接收。Laravel 框架附带的默认 BroadcastServiceProvider 中包含了 App.Models.User.{id} 频道的频道授权回调。

版权所有 © 2024-2025 laravel.wiki