广播

简介

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

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

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

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

支持的驱动

默认情况下，Laravel 包含三个服务器端广播驱动供你选择：Laravel Reverb、Pusher Channels 和 Ably。

NOTE

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

快速入门

默认情况下，新的 Laravel 应用程序未启用广播。你可以使用 install:broadcasting Artisan 命令启用广播：

shell

php artisan install:broadcasting

install:broadcasting 命令会提示你选择要使用的事件广播服务。此外，它将创建 config/broadcasting.php 配置文件和 routes/channels.php 文件，你可以在其中注册应用程序的广播授权路由和回调。

Laravel 开箱即用地支持多种广播驱动：Laravel Reverb、Pusher Channels、Ably，以及用于本地开发和调试的 log 驱动。此外，还包含一个 null 驱动，允许你在测试期间禁用广播。config/broadcasting.php 配置文件中包含了每个驱动的配置示例。

所有应用程序的事件广播配置都存储在 config/broadcasting.php 配置文件中。如果此文件在你的应用程序中不存在，不用担心；它将在你运行 install:broadcasting Artisan 命令时创建。

后续步骤

启用事件广播后，你就可以了解更多关于定义广播事件和监听事件的信息。如果你使用 Laravel 的 React 或 Vue 入门套件，可以使用 Echo 的 useEcho hook 来监听事件。

NOTE

在广播任何事件之前，你应该先配置并运行一个队列工作者。所有事件广播都是通过队列任务完成的，这样你的应用程序的响应时间不会受到事件广播的严重影响。

服务器端安装

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

事件广播由服务器端广播驱动完成，该驱动广播你的 Laravel 事件，以便 Laravel Echo（一个 JavaScript 库）可以在浏览器客户端中接收它们。不用担心——我们将逐步引导你完成安装过程的每个部分。

Reverb

要在使用 Reverb 作为事件广播器时快速启用 Laravel 广播功能的支持，请使用 --reverb 选项调用 install:broadcasting Artisan 命令。此 Artisan 命令将安装 Reverb 所需的 Composer 和 NPM 包，并使用适当的变量更新应用程序的 .env 文件：

shell

php artisan install:broadcasting --reverb

手动安装

运行 install:broadcasting 命令时，系统会提示你安装 Laravel Reverb。当然，你也可以使用 Composer 包管理器手动安装 Reverb：

shell

composer require laravel/reverb

安装包后，你可以运行 Reverb 的安装命令来发布配置、添加 Reverb 所需的环境变量，并在应用程序中启用事件广播：

shell

php artisan reverb:install

你可以在 Reverb 文档中找到详细的 Reverb 安装和使用说明。

Pusher Channels

要在使用 Pusher 作为事件广播器时快速启用 Laravel 广播功能的支持，请使用 --pusher 选项调用 install:broadcasting Artisan 命令。此 Artisan 命令会提示你输入 Pusher 凭据，安装 Pusher PHP 和 JavaScript SDK，并使用适当的变量更新应用程序的 .env 文件：

shell

php artisan install:broadcasting --pusher

手动安装

要手动安装 Pusher 支持，你应该使用 Composer 包管理器安装 Pusher Channels PHP SDK：

shell

composer require pusher/pusher-php-server

接下来，你应该在 config/broadcasting.php 配置文件中配置你的 Pusher Channels 凭据。此文件中已包含一个 Pusher Channels 配置示例，允许你快速指定密钥、密钥和应用程序 ID。通常，你应该在应用程序的 .env 文件中配置 Pusher Channels 凭据：

ini

PUSHER_APP_ID="your-pusher-app-id"
PUSHER_APP_KEY="your-pusher-key"
PUSHER_APP_SECRET="your-pusher-secret"
PUSHER_HOST=
PUSHER_PORT=443
PUSHER_SCHEME="https"
PUSHER_APP_CLUSTER="mt1"

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

然后，在应用程序的 .env 文件中将 BROADCAST_CONNECTION 环境变量设置为 pusher：

ini

BROADCAST_CONNECTION=pusher

最后，你可以安装和配置 Laravel Echo，它将在客户端接收广播事件。

Ably

NOTE

以下文档讨论了如何在 "Pusher 兼容" 模式下使用 Ably。但是，Ably 团队推荐并维护了一个能够利用 Ably 提供的独特功能的广播器和 Echo 客户端。有关使用 Ably 维护的驱动的更多信息，请查阅 Ably 的 Laravel 广播器文档。

要在使用 Ably 作为事件广播器时快速启用 Laravel 广播功能的支持，请使用 --ably 选项调用 install:broadcasting Artisan 命令。此 Artisan 命令会提示你输入 Ably 凭据，安装 Ably PHP 和 JavaScript SDK，并使用适当的变量更新应用程序的 .env 文件：

shell

php artisan install:broadcasting --ably

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

手动安装

要手动安装 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 文件中将 BROADCAST_CONNECTION 环境变量设置为 ably：

ini

BROADCAST_CONNECTION=ably

最后，你可以安装和配置 Laravel Echo，它将在客户端接收广播事件。

客户端安装

Reverb

Laravel Echo 是一个 JavaScript 库，它使订阅通道和监听服务器端广播驱动广播的事件变得轻松。

通过 install:broadcasting Artisan 命令安装 Laravel Reverb 时，Reverb 和 Echo 的脚手架和配置将自动注入到你的应用程序中。但是，如果你希望手动配置 Laravel Echo，可以按照以下说明进行。

手动安装

要为应用程序的前端手动配置 Laravel Echo，首先安装 pusher-js 包，因为 Reverb 使用 Pusher 协议进行 WebSocket 订阅、通道和消息：

shell

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

Echo 安装完成后，你就可以在应用程序的 JavaScript 中创建一个新的 Echo 实例。一个很好的位置是在 Laravel 框架附带的 resources/js/bootstrap.js 文件的底部：

JavaScriptReactVue

import Echo from 'laravel-echo';

import Pusher from 'pusher-js';
window.Pusher = Pusher;

window.Echo = new Echo({
    broadcaster: 'reverb',
    key: import.meta.env.VITE_REVERB_APP_KEY,
    wsHost: import.meta.env.VITE_REVERB_HOST,
    wsPort: import.meta.env.VITE_REVERB_PORT ?? 80,
    wssPort: import.meta.env.VITE_REVERB_PORT ?? 443,
    forceTLS: (import.meta.env.VITE_REVERB_SCHEME ?? 'https') === 'https',
    enabledTransports: ['ws', 'wss'],
});

import { configureEcho } from "@laravel/echo-react";

configureEcho({
    broadcaster: "reverb",
    // key: import.meta.env.VITE_REVERB_APP_KEY,
    // wsHost: import.meta.env.VITE_REVERB_HOST,
    // wsPort: import.meta.env.VITE_REVERB_PORT,
    // wssPort: import.meta.env.VITE_REVERB_PORT,
    // forceTLS: (import.meta.env.VITE_REVERB_SCHEME ?? 'https') === 'https',
    // enabledTransports: ['ws', 'wss'],
});

import { configureEcho } from "@laravel/echo-vue";

configureEcho({
    broadcaster: "reverb",
    // key: import.meta.env.VITE_REVERB_APP_KEY,
    // wsHost: import.meta.env.VITE_REVERB_HOST,
    // wsPort: import.meta.env.VITE_REVERB_PORT,
    // wssPort: import.meta.env.VITE_REVERB_PORT,
    // forceTLS: (import.meta.env.VITE_REVERB_SCHEME ?? 'https') === 'https',
    // enabledTransports: ['ws', 'wss'],
});

接下来，你应该编译应用程序的资源：

shell

npm run build

WARNING

Laravel Echo reverb 广播器需要 laravel-echo v1.16.0+。

Pusher Channels

Laravel Echo 是一个 JavaScript 库，它使订阅通道和监听服务器端广播驱动广播的事件变得轻松。

通过 install:broadcasting --pusher Artisan 命令安装广播支持时，Pusher 和 Echo 的脚手架和配置将自动注入到你的应用程序中。但是，如果你希望手动配置 Laravel Echo，可以按照以下说明进行。

手动安装

要为应用程序的前端手动配置 Laravel Echo，首先安装 laravel-echo 和 pusher-js 包，它们使用 Pusher 协议进行 WebSocket 订阅、通道和消息：

shell

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

Echo 安装完成后，你就可以在应用程序的 resources/js/bootstrap.js 文件中创建一个新的 Echo 实例：

JavaScriptReactVue

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
});

import { configureEcho } from "@laravel/echo-react";

configureEcho({
    broadcaster: "pusher",
    // key: import.meta.env.VITE_PUSHER_APP_KEY,
    // cluster: import.meta.env.VITE_PUSHER_APP_CLUSTER,
    // forceTLS: true,
    // wsHost: import.meta.env.VITE_PUSHER_HOST,
    // wsPort: import.meta.env.VITE_PUSHER_PORT,
    // wssPort: import.meta.env.VITE_PUSHER_PORT,
    // enabledTransports: ["ws", "wss"],
});

import { configureEcho } from "@laravel/echo-vue";

configureEcho({
    broadcaster: "pusher",
    // key: import.meta.env.VITE_PUSHER_APP_KEY,
    // cluster: import.meta.env.VITE_PUSHER_APP_CLUSTER,
    // forceTLS: true,
    // wsHost: import.meta.env.VITE_PUSHER_HOST,
    // wsPort: import.meta.env.VITE_PUSHER_PORT,
    // wssPort: import.meta.env.VITE_PUSHER_PORT,
    // enabledTransports: ["ws", "wss"],
});

接下来，你应该在应用程序的 .env 文件中为 Pusher 环境变量定义适当的值。如果这些变量尚未存在于你的 .env 文件中，你应该添加它们：

ini

PUSHER_APP_ID="your-pusher-app-id"
PUSHER_APP_KEY="your-pusher-key"
PUSHER_APP_SECRET="your-pusher-secret"
PUSHER_HOST=
PUSHER_PORT=443
PUSHER_SCHEME="https"
PUSHER_APP_CLUSTER="mt1"

VITE_APP_NAME="${APP_NAME}"
VITE_PUSHER_APP_KEY="${PUSHER_APP_KEY}"
VITE_PUSHER_HOST="${PUSHER_HOST}"
VITE_PUSHER_PORT="${PUSHER_PORT}"
VITE_PUSHER_SCHEME="${PUSHER_SCHEME}"
VITE_PUSHER_APP_CLUSTER="${PUSHER_APP_CLUSTER}"

根据应用程序的需要调整 Echo 配置后，你可以编译应用程序的资源：

shell

npm run build

NOTE

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

使用现有客户端实例

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

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

const options = {
    broadcaster: 'pusher',
    key: import.meta.env.VITE_PUSHER_APP_KEY
}

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

Ably

NOTE

Laravel Echo 是一个 JavaScript 库，它使订阅通道和监听服务器端广播驱动广播的事件变得轻松。

通过 install:broadcasting --ably Artisan 命令安装广播支持时，Ably 和 Echo 的脚手架和配置将自动注入到你的应用程序中。但是，如果你希望手动配置 Laravel Echo，可以按照以下说明进行。

手动安装

要为应用程序的前端手动配置 Laravel Echo，首先安装 laravel-echo 和 pusher-js 包，它们使用 Pusher 协议进行 WebSocket 订阅、通道和消息：

shell

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

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

Echo 安装完成后，你就可以在应用程序的 resources/js/bootstrap.js 文件中创建一个新的 Echo 实例：

JavaScriptReactVue

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,
});

import { configureEcho } from "@laravel/echo-react";

configureEcho({
    broadcaster: "ably",
    // key: import.meta.env.VITE_ABLY_PUBLIC_KEY,
    // wsHost: "realtime-pusher.ably.io",
    // wsPort: 443,
    // disableStats: true,
    // encrypted: true,
});

import { configureEcho } from "@laravel/echo-vue";

configureEcho({
    broadcaster: "ably",
    // 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

NOTE

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

概念概述

Laravel 的事件广播允许你使用基于驱动的 WebSocket 方法将服务器端的 Laravel 事件广播到客户端的 JavaScript 应用程序。目前，Laravel 附带了 Laravel Reverb、Pusher Channels 和 Ably 驱动。可以使用 Laravel Echo JavaScript 包在客户端轻松消费这些事件。

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

使用示例应用程序

在深入事件广播的每个组成部分之前，让我们以电子商务商店为例进行高层概述。

在我们的应用程序中，假设我们有一个页面允许用户查看其订单的发货状态。让我们还假设当应用程序处理发货状态更新时会触发 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\Contracts\Broadcasting\ShouldBroadcast;
use Illuminate\Queue\SerializesModels;

class OrderShipmentStatusUpdated implements ShouldBroadcast
{
    /**
     * The order instance.
     *
     * @var \App\Models\Order
     */
    public $order;
}

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

php

use Illuminate\Broadcasting\Channel;
use Illuminate\Broadcasting\PrivateChannel;

/**
 * Get the channel the event should broadcast on.
 */
public function broadcastOn(): Channel
{
    return new PrivateChannel('orders.'.$this->order->id);
}

如果你希望事件在多个通道上广播，可以返回一个 array：

php

use Illuminate\Broadcasting\PrivateChannel;

/**
 * Get the channels the event should broadcast on.
 *
 * @return array<int, \Illuminate\Broadcasting\Channel>
 */
public function broadcastOn(): array
{
    return [
        new PrivateChannel('orders.'.$this->order->id),
        // ...
    ];
}

授权通道

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

php

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

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

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

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

监听事件广播

接下来，剩下的就是在我们的 JavaScript 应用程序中监听事件。我们可以使用 Laravel Echo 来完成此操作。Laravel Echo 内置的 React 和 Vue hooks 使入门变得简单，而且默认情况下，事件的所有公共属性都将包含在广播事件中：

ReactVue

import { useEcho } from "@laravel/echo-react";

useEcho(
    `orders.${orderId}`,
    "OrderShipmentStatusUpdated",
    (e) => {
        console.log(e.order);
    },
);

vue

<script setup lang="ts">
import { useEcho } from "@laravel/echo-vue";

useEcho(
    `orders.${orderId}`,
    "OrderShipmentStatusUpdated",
    (e) => {
        console.log(e.order);
    },
);
</script>

定义广播事件

要通知 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;

    /**
     * Create a new event instance.
     */
    public function __construct(
        public User $user,
    ) {}

    /**
     * Get the channels the event should broadcast on.
     *
     * @return array<int, \Illuminate\Broadcasting\Channel>
     */
    public function broadcastOn(): array
    {
        return [
            new PrivateChannel('user.'.$this->user->id),
        ];
    }
}

实现 ShouldBroadcast 接口后，你只需要像平常一样触发事件。一旦事件被触发，一个队列任务将使用你指定的广播驱动自动广播事件。

广播名称

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

php

/**
 * The event's broadcast name.
 */
public function broadcastAs(): string
{
    return 'server.created';
}

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

javascript

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

广播数据

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

json

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

但是，如果你希望对广播负载有更精细的控制，可以在事件中添加 broadcastWith 方法。此方法应返回你希望作为事件负载广播的数据数组：

php

/**
 * Get the data to broadcast.
 *
 * @return array<string, mixed>
 */
public function broadcastWith(): array
{
    return ['id' => $this->user->id];
}

广播队列

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

php

use Illuminate\Queue\Attributes\Connection;
use Illuminate\Queue\Attributes\Queue;

#[Connection('redis')]
#[Queue('default')]
class ServerCreated implements ShouldBroadcast
{
    // ...
}

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

php

/**
 * The name of the queue on which to place the broadcasting job.
 */
public function broadcastQueue(): string
{
    return 'default';
}

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

php

<?php

namespace App\Events;

use Illuminate\Contracts\Broadcasting\ShouldBroadcastNow;

class OrderShipmentStatusUpdated implements ShouldBroadcastNow
{
    // ...
}

广播条件

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

php

/**
 * Determine if this event should broadcast.
 */
public function broadcastWhen(): bool
{
    return $this->order->value > 100;
}

广播与数据库事务

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

如果你的队列连接的 after_commit 配置选项设置为 false，你仍然可以通过在事件类上实现 ShouldDispatchAfterCommit 接口来指示特定的广播事件应在所有打开的数据库事务提交后再分发：

php

<?php

namespace App\Events;

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

class ServerCreated implements ShouldBroadcast, ShouldDispatchAfterCommit
{
    use SerializesModels;
}

NOTE

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

授权通道

私有通道要求你授权当前经过身份验证的用户确实可以在该通道上监听。这是通过向你的 Laravel 应用程序发起包含通道名称的 HTTP 请求并允许你的应用程序确定用户是否可以在该通道上监听来完成的。使用 Laravel Echo 时，授权订阅私有通道的 HTTP 请求将自动发起。

安装广播时，Laravel 会尝试自动注册 /broadcasting/auth 路由来处理授权请求。如果 Laravel 未能自动注册这些路由，你可以在应用程序的 /bootstrap/app.php 文件中手动注册它们：

php

->withRouting(
    web: __DIR__.'/../routes/web.php',
    channels: __DIR__.'/../routes/channels.php',
    health: '/up',
)

定义授权回调

接下来，我们需要定义实际确定当前经过身份验证的用户是否可以监听给定通道的逻辑。这是在由 install:broadcasting Artisan 命令创建的 routes/channels.php 文件中完成的。在此文件中，你可以使用 Broadcast::channel 方法注册通道授权回调：

php

use App\Models\User;

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

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

你可以使用 channel:list Artisan 命令查看应用程序的广播授权回调列表：

shell

php artisan channel:list

授权回调模型绑定

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

php

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

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

WARNING

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

授权回调身份验证

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

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
{
    /**
     * Create a new channel instance.
     */
    public function __construct() {}

    /**
     * Authenticate the user's access to the channel.
     */
    public function join(User $user, Order $order): array|bool
    {
        return $user->id === $order->user_id;
    }
}

NOTE

像 Laravel 中的许多其他类一样，通道类将自动由 service container 解析。因此，你可以在其构造函数中类型提示通道所需的任何依赖。

广播事件

一旦你定义了事件并使用 ShouldBroadcast 接口标记了它，你只需要使用事件的 dispatch 方法触发事件。事件分发器会注意到事件被标记了 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 应用程序从端点收到响应时，它可能会直接将新任务插入其任务列表中：

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

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

WARNING

你的事件必须使用 Illuminate\Broadcasting\InteractsWithSockets trait 才能调用 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：

var socketId = Echo.socketId();

自定义连接

如果你的应用程序与多个广播连接交互，并且你想使用默认广播器以外的广播器广播事件，你可以使用 via 方法指定将事件推送到哪个连接：

php

use App\Events\OrderShipmentStatusUpdated;

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

或者，你可以通过在事件的构造函数中调用 broadcastVia 方法来指定事件的广播连接。但是，在此之前，你应该确保事件类使用了 InteractsWithBroadcasting trait：

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;

    /**
     * Create a new event instance.
     */
    public function __construct()
    {
        $this->broadcastVia('pusher');
    }
}

匿名事件

有时，你可能希望向应用程序的前端广播一个简单的事件，而无需创建专用的事件类。为此，Broadcast facade 允许你广播“匿名事件”：

php

Broadcast::on('orders.'.$order->id)->send();

上面的示例将广播以下事件：

json

{
    "event": "AnonymousEvent",
    "data": "[]",
    "channel": "orders.1"
}

使用 as 和 with 方法，你可以自定义事件的名称和数据：

php

Broadcast::on('orders.'.$order->id)
    ->as('OrderPlaced')
    ->with($order)
    ->send();

上面的示例将广播类似以下的事件：

json

{
    "event": "OrderPlaced",
    "data": "{ id: 1, total: 100 }",
    "channel": "orders.1"
}

如果你希望在私有或 Presence 通道上广播匿名事件，可以使用 private 和 presence 方法：

php

Broadcast::private('orders.'.$order->id)->send();
Broadcast::presence('channels.'.$channel->id)->send();

使用 send 方法广播匿名事件会将事件分发到应用程序的队列进行处理。但是，如果你希望立即广播事件，可以使用 sendNow 方法：

php

Broadcast::on('orders.'.$order->id)->sendNow();

要将事件广播给除当前经过身份验证的用户之外的所有通道订阅者，你可以调用 toOthers 方法：

php

Broadcast::on('orders.'.$order->id)
    ->toOthers()
    ->send();

救援广播

当应用程序的队列服务器不可用或 Laravel 在广播事件时遇到错误时，会抛出异常，通常会导致最终用户看到应用程序错误。由于事件广播通常是应用程序核心功能的补充，你可以通过在事件上实现 ShouldRescue 接口来防止这些异常影响用户体验。

实现 ShouldRescue 接口的事件在广播尝试期间会自动使用 Laravel 的 rescue 辅助函数。此辅助函数会捕获任何异常，将它们报告给应用程序的异常处理程序进行日志记录，并允许应用程序继续正常执行而不会中断用户的工作流程：

php

<?php

namespace App\Events;

use Illuminate\Contracts\Broadcasting\ShouldBroadcast;
use Illuminate\Contracts\Broadcasting\ShouldRescue;

class ServerCreated implements ShouldBroadcast, ShouldRescue
{
    // ...
}

接收广播

监听事件

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

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

如果你想在私有通道上监听事件，请改用 private 方法。你可以继续链式调用 listen 方法以在单个通道上监听多个事件：

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

停止监听事件

如果你想停止监听给定事件而不离开通道，可以使用 stopListening 方法：

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

离开通道

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

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

如果你想离开通道及其关联的私有和 Presence 通道，可以调用 leave 方法：

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

命名空间

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

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

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

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

使用 React 或 Vue

Laravel Echo 包含 React 和 Vue hooks，使监听事件变得轻松。首先，调用 useEcho hook，它用于监听私有事件。useEcho hook 会在使用它的组件卸载时自动离开通道：

ReactVue

import { useEcho } from "@laravel/echo-react";

useEcho(
    `orders.${orderId}`,
    "OrderShipmentStatusUpdated",
    (e) => {
        console.log(e.order);
    },
);

vue

<script setup lang="ts">
import { useEcho } from "@laravel/echo-vue";

useEcho(
    `orders.${orderId}`,
    "OrderShipmentStatusUpdated",
    (e) => {
        console.log(e.order);
    },
);
</script>

你可以通过向 useEcho 提供事件数组来监听多个事件：

useEcho(
    `orders.${orderId}`,
    ["OrderShipmentStatusUpdated", "OrderShipped"],
    (e) => {
        console.log(e.order);
    },
);

你还可以指定广播事件负载数据的形状，提供更强的类型安全性和编辑便利性：

type OrderData = {
    order: {
        id: number;
        user: {
            id: number;
            name: string;
        };
        created_at: string;
    };
};

useEcho<OrderData>(`orders.${orderId}`, "OrderShipmentStatusUpdated", (e) => {
    console.log(e.order.id);
    console.log(e.order.user.id);
});

useEcho hook 会在使用它的组件卸载时自动离开通道；但是，你可以利用返回的函数在需要时以编程方式手动停止/开始监听通道：

ReactVue

import { useEcho } from "@laravel/echo-react";

const { leaveChannel, leave, stopListening, listen } = useEcho(
    `orders.${orderId}`,
    "OrderShipmentStatusUpdated",
    (e) => {
        console.log(e.order);
    },
);

// 停止监听但不离开通道...
stopListening();

// 重新开始监听...
listen();

// 离开通道...
leaveChannel();

// 离开通道及其关联的私有和 Presence 通道...
leave();

vue

<script setup lang="ts">
import { useEcho } from "@laravel/echo-vue";

const { leaveChannel, leave, stopListening, listen } = useEcho(
    `orders.${orderId}`,
    "OrderShipmentStatusUpdated",
    (e) => {
        console.log(e.order);
    },
);

// 停止监听但不离开通道...
stopListening();

// 重新开始监听...
listen();

// 离开通道...
leaveChannel();

// 离开通道及其关联的私有和 Presence 通道...
leave();
</script>

连接到公共通道

要连接到公共通道，你可以使用 useEchoPublic hook：

ReactVue

import { useEchoPublic } from "@laravel/echo-react";

useEchoPublic("posts", "PostPublished", (e) => {
    console.log(e.post);
});

vue

<script setup lang="ts">
import { useEchoPublic } from "@laravel/echo-vue";

useEchoPublic("posts", "PostPublished", (e) => {
    console.log(e.post);
});
</script>

连接到 Presence 通道

要连接到 Presence 通道，你可以使用 useEchoPresence hook：

ReactVue

import { useEchoPresence } from "@laravel/echo-react";

useEchoPresence("posts", "PostPublished", (e) => {
    console.log(e.post);
});

vue

<script setup lang="ts">
import { useEchoPresence } from "@laravel/echo-vue";

useEchoPresence("posts", "PostPublished", (e) => {
    console.log(e.post);
});
</script>

连接状态

你可以使用 useConnectionStatus hook 获取当前 WebSocket 连接状态，它提供响应式状态，在连接状态改变时自动更新：

ReactVue

import { useConnectionStatus } from "@laravel/echo-react";

function ConnectionIndicator() {
    const status = useConnectionStatus();

    return <div>Connection: {status}</div>;
}

vue

<script setup lang="ts">
import { useConnectionStatus } from "@laravel/echo-vue";

const status = useConnectionStatus();
</script>

<template>
    <div>Connection: {{ status }}</div>
</template>

可能的状态值为：

connected - 已成功连接到 WebSocket 服务器。
connecting - 正在进行初始连接尝试。
reconnecting - 断开连接后正在尝试重新连接。
disconnected - 未连接且未尝试重新连接。
failed - 连接失败且不会重试。

Presence 通道

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

授权 Presence 通道

所有 Presence 通道也是私有通道；因此，用户必须被授权访问它们。但是，在为 Presence 通道定义授权回调时，如果用户被授权加入通道，你不应返回 true。相反，你应该返回一个包含用户数据的数组。

授权回调返回的数据将在你的 JavaScript 应用程序中提供给 Presence 通道事件监听器。如果用户未被授权加入 Presence 通道，你应该返回 false 或 null：

php

use App\Models\User;

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

加入 Presence 通道

要加入 Presence 通道，你可以使用 Echo 的 join 方法。join 方法将返回一个 PresenceChannel 实现，它在暴露 listen 方法的同时，还允许你订阅 here、joining 和 leaving 事件。

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 方法将在身份验证端点返回非 200 的 HTTP 状态码或解析返回的 JSON 出现问题时执行。

向 Presence 通道广播

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

php

/**
 * Get the channels the event should broadcast on.
 *
 * @return array<int, \Illuminate\Broadcasting\Channel>
 */
public function broadcastOn(): array
{
    return [
        new PresenceChannel('chat.'.$this->message->room_id),
    ];
}

与其他事件一样，你可以使用 broadcast 辅助函数和 toOthers 方法来排除当前用户接收广播：

php

broadcast(new NewMessage($message));

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

与其他类型的事件一样，你可以使用 Echo 的 listen 方法监听发送到 Presence 通道的事件：

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

模型广播

WARNING

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

当应用程序的 Eloquent 模型被创建、更新或删除时，广播事件是很常见的。当然，这可以通过手动为 Eloquent 模型状态变化定义自定义事件并使用 ShouldBroadcast 接口标记这些事件来轻松完成。

但是，如果你在应用程序中没有将这些事件用于任何其他目的，那么仅为了广播而创建事件类可能会很繁琐。为了解决这个问题，Laravel 允许你指示 Eloquent 模型应自动广播其状态变化。

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

php

<?php

namespace App\Models;

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

class Post extends Model
{
    use BroadcastsEvents, HasFactory;

    /**
     * Get the user that the post belongs to.
     */
    public function user(): BelongsTo
    {
        return $this->belongsTo(User::class);
    }

    /**
     * Get the channels that model events should broadcast on.
     *
     * @return array<int, \Illuminate\Broadcasting\Channel|\Illuminate\Database\Eloquent\Model>
     */
    public function broadcastOn(string $event): array
    {
        return [$this, $this->user];
    }
}

一旦你的模型包含此 trait 并定义了其广播通道，它将在模型实例被创建、更新、删除、软删除或恢复时自动开始广播事件。

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

php

/**
 * Get the channels that model events should broadcast on.
 *
 * @return array<string, array<int, \Illuminate\Broadcasting\Channel|\Illuminate\Database\Eloquent\Model>>
 */
public function broadcastOn(string $event): array
{
    return match ($event) {
        'deleted' => [],
        default => [$this, $this->user],
    };
}

自定义模型广播事件创建

有时，你可能希望自定义 Laravel 创建底层模型广播事件的方式。你可以通过在 Eloquent 模型上定义 newBroadcastableEvent 方法来完成此操作。此方法应返回一个 Illuminate\Database\Eloquent\BroadcastableModelEventOccurred 实例：

php

use Illuminate\Database\Eloquent\BroadcastableModelEventOccurred;

/**
 * Create a new broadcastable model event for the model.
 */
protected function newBroadcastableEvent(string $event): BroadcastableModelEventOccurred
{
    return (new BroadcastableModelEventOccurred(
        $this, $event
    ))->dontBroadcastToCurrentUser();
}

模型广播约定

通道约定

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

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

php

use Illuminate\Broadcasting\PrivateChannel;

/**
 * Get the channels that model events should broadcast on.
 *
 * @return array<int, \Illuminate\Broadcasting\Channel>
 */
public function broadcastOn(string $event): array
{
    return [
        new PrivateChannel('user.'.$this->id)
    ];
}

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

php

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

如果你需要确定模型的通道名称，可以在任何模型实例上调用 broadcastChannel 方法。例如，对于 id 为 1 的 App\Models\User 模型，此方法返回字符串 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

/**
 * The model event's broadcast name.
 */
public function broadcastAs(string $event): string|null
{
    return match ($event) {
        'created' => 'post.created',
        default => null,
    };
}

/**
 * Get the data to broadcast for the model.
 *
 * @return array<string, mixed>
 */
public function broadcastWith(string $event): array
{
    return match ($event) {
        'created' => ['title' => $this->title],
        default => ['model' => $this],
    };
}

监听模型广播

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

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

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

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

使用 React 或 Vue

如果你使用 React 或 Vue，可以使用 Laravel Echo 包含的 useEchoModel hook 轻松监听模型广播：

ReactVue

import { useEchoModel } from "@laravel/echo-react";

useEchoModel("App.Models.User", userId, ["UserUpdated"], (e) => {
    console.log(e.model);
});

vue

<script setup lang="ts">
import { useEchoModel } from "@laravel/echo-vue";

useEchoModel("App.Models.User", userId, ["UserUpdated"], (e) => {
    console.log(e.model);
});
</script>

你还可以指定模型事件负载数据的形状，提供更强的类型安全性和编辑便利性：

type User = {
    id: number;
    name: string;
    email: string;
};

useEchoModel<User, "App.Models.User">("App.Models.User", userId, ["UserUpdated"], (e) => {
    console.log(e.model.id);
    console.log(e.model.name);
});

客户端事件

NOTE

使用 Pusher Channels 时，你必须在应用程序仪表板的“App Settings”部分启用“Client Events”选项才能发送客户端事件。

有时你可能希望将事件广播给其他连接的客户端，而完全不经过你的 Laravel 应用程序。这对于“正在输入”通知等场景特别有用，你希望提醒应用程序的用户另一个用户正在给定屏幕上输入消息。

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

JavaScriptReactVue

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

import { useEcho } from "@laravel/echo-react";

const { channel } = useEcho(`chat.${roomId}`, ['update'], (e) => {
    console.log('Chat event received:', e);
});

channel().whisper('typing', { name: user.name });

vue

<script setup lang="ts">
import { useEcho } from "@laravel/echo-vue";

const { channel } = useEcho(`chat.${roomId}`, ['update'], (e) => {
    console.log('Chat event received:', e);
});

channel().whisper('typing', { name: user.name });
</script>

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

JavaScriptReactVue

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

import { useEcho } from "@laravel/echo-react";

const { channel } = useEcho(`chat.${roomId}`, ['update'], (e) => {
    console.log('Chat event received:', e);
});

channel().listenForWhisper('typing', (e) => {
    console.log(e.name);
});

vue

<script setup lang="ts">
import { useEcho } from "@laravel/echo-vue";

const { channel } = useEcho(`chat.${roomId}`, ['update'], (e) => {
    console.log('Chat event received:', e);
});

channel().listenForWhisper('typing', (e) => {
    console.log(e.name);
});
</script>

通知

通过将事件广播与通知配对，你的 JavaScript 应用程序可以在新通知发生时接收它们，而无需刷新页面。在开始之前，请确保阅读了使用广播通知通道的文档。

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

JavaScriptReactVue

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

import { useEchoModel } from "@laravel/echo-react";

const { channel } = useEchoModel('App.Models.User', userId);

channel().notification((notification) => {
    console.log(notification.type);
});

vue

<script setup lang="ts">
import { useEchoModel } from "@laravel/echo-vue";

const { channel } = useEchoModel('App.Models.User', userId);

channel().notification((notification) => {
    console.log(notification.type);
});
</script>

在此示例中，通过 broadcast 通道发送给 App\Models\User 实例的所有通知都将被回调接收。App.Models.User.{id} 通道的通道授权回调包含在应用程序的 routes/channels.php 文件中。

停止监听通知

如果你想停止监听通知而不离开通道，可以使用 stopListeningForNotification 方法：

const callback = (notification) => {
    console.log(notification.type);
}

// 开始监听...
Echo.private(`App.Models.User.${userId}`)
    .notification(callback);

// 停止监听（回调必须是同一个）...
Echo.private(`App.Models.User.${userId}`)
    .stopListeningForNotification(callback);

广播 ​

简介 ​

支持的驱动 ​

快速入门 ​

后续步骤 ​

服务器端安装 ​

Reverb ​

手动安装 ​

Pusher Channels ​

手动安装 ​

Ably ​

手动安装 ​

客户端安装 ​

Reverb ​

手动安装 ​

Pusher Channels ​

手动安装 ​

使用现有客户端实例 ​

Ably ​

手动安装 ​

概念概述 ​

使用示例应用程序 ​

ShouldBroadcast 接口 ​

授权通道 ​

监听事件广播 ​

定义广播事件 ​

广播名称 ​

广播数据 ​

广播队列 ​

广播条件 ​

广播与数据库事务 ​

授权通道 ​

定义授权回调 ​

授权回调模型绑定 ​

授权回调身份验证 ​

定义通道类 ​

广播事件 ​

仅广播给其他人 ​

配置 ​

自定义连接 ​

匿名事件 ​

救援广播 ​

接收广播 ​

监听事件 ​

停止监听事件 ​

离开通道 ​

命名空间 ​

使用 React 或 Vue ​

连接到公共通道 ​

连接到 Presence 通道 ​

连接状态 ​

Presence 通道 ​

授权 Presence 通道 ​

加入 Presence 通道 ​

向 Presence 通道广播 ​

模型广播 ​

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

模型广播约定 ​

通道约定 ​

事件约定 ​

监听模型广播 ​

使用 React 或 Vue ​

客户端事件 ​

通知 ​

停止监听通知 ​

广播

简介

支持的驱动

快速入门

后续步骤

服务器端安装

Reverb

手动安装

Pusher Channels

手动安装

Ably

手动安装

客户端安装

Reverb

手动安装

Pusher Channels

手动安装

使用现有客户端实例

Ably

手动安装

概念概述

使用示例应用程序

`ShouldBroadcast` 接口

授权通道

监听事件广播

定义广播事件

广播名称

广播数据

广播队列

广播条件

广播与数据库事务

授权通道

定义授权回调

授权回调模型绑定

授权回调身份验证

定义通道类

广播事件

仅广播给其他人

配置

自定义连接

匿名事件

救援广播

接收广播

监听事件

停止监听事件

离开通道

命名空间

使用 React 或 Vue

连接到公共通道

连接到 Presence 通道

连接状态

Presence 通道

授权 Presence 通道

加入 Presence 通道

向 Presence 通道广播

模型广播

自定义模型广播事件创建

模型广播约定

通道约定

事件约定

监听模型广播

使用 React 或 Vue

客户端事件

通知

停止监听通知