广播

介绍
快速开始
服务器端安装
客户端安装
概念概述
- 使用示例应用程序
定义广播事件
授权频道
- 定义授权回调
- 定义频道类
广播事件
接收广播
在线频道
模型广播
- 模型广播约定
- 监听模型广播
客户端事件
通知

介绍

在许多现代 Web 应用程序中，WebSockets 用于实现实时、实时更新的用户界面。当服务器上的某些数据更新时，通常会通过 WebSocket 连接发送消息以由客户端处理。WebSockets 提供了一种更高效的替代方案，以不断轮询应用程序的服务器以获取应在 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 团队推荐并维护了一个广播器和 Echo 客户端，能够利用 Ably 提供的独特功能。有关使用 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 应用程序设置仪表板的“协议适配器设置”部分启用此功能。

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 的事件广播允许您使用基于驱动的 WebSockets 方法，将服务端的 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
{
    /**
     * 订单实例。
     *
     * @var \App\Models\Order
     */
    public $order;
}

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

php

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

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

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

php

use Illuminate\Broadcasting\PrivateChannel;

/**
 * 获取事件应广播的频道。
 *
 * @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;

    /**
     * 创建一个新的事件实例。
     */
    public function __construct(
        public User $user,
    ) {}

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

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

广播名称

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

php

/**
 * 事件的广播名称。
 */
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

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

广播队列

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

php

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

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

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

php

/**
 * 要放置广播作业的队列的名称。
 */
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

/**
 * 确定此事件是否应广播。
 */
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 路由以处理授权请求。/broadcasting/auth 路由会自动放置在 web 中间件组中。

定义授权回调

接下来，我们需要定义实际确定当前经过身份验证的用户是否可以收听给定频道的逻辑。这是在 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 路由模型绑定不同，频道模型绑定不支持自动隐式模型绑定作用域。然而，这很少是一个问题，因为大多数频道可以基于单个模型的唯一主键进行作用域。

授权回调身份验证

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

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
{
    /**
     * 创建一个新的频道实例。
     */
    public function __construct() {}

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

NOTE

像 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 应用程序从端点接收到响应时，它可能会直接将新任务插入到其任务列表中，如下所示：

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;

    /**
     * 创建一个新的事件实例。
     */
    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"
}

如果您希望在私有或存在频道上广播匿名事件，您可以使用 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}`);

如果您希望离开频道及其关联的私有和存在频道，您可以调用 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();

// 离开频道及其相关的私有和在线频道...
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();

// 离开频道及其相关的私有和在线频道...
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>

连接到在线频道

要连接到在线频道，可以使用 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>

存在频道

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

授权存在频道

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

授权回调返回的数据将提供给 JavaScript 应用程序中的存在频道事件监听器。如果用户未被授权加入存在频道，您应该返回 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];
    }
});

加入存在频道

要加入存在频道，您可以使用 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 方法。当身份验证端点返回 HTTP 状态码不是 200 或解析返回的 JSON 时出现问题时，将执行 error 方法。

广播到存在频道

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

php

/**
 * 获取事件应广播的频道。
 *
 * @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 方法监听发送到存在频道的事件：

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;

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

    /**
     * 获取模型事件应广播的频道。
     *
     * @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

/**
 * 获取模型事件应广播的频道。
 *
 * @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;

/**
 * 为模型创建一个新的可广播模型事件。
 */
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;

/**
 * 获取模型事件应广播的频道。
 *
 * @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

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

/**
 * 获取模型的广播数据。
 *
 * @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 时，您必须在应用程序仪表板的“应用程序设置”部分中启用“客户端事件”选项，以便发送客户端事件。

有时，您可能希望将事件广播到其他连接的客户端，而无需访问您的 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 文件中。

广播 ​

介绍 ​

支持的驱动程序 ​

快速开始 ​

下一步 ​

服务器端安装 ​

Reverb ​

手动安装 ​

Pusher Channels ​

手动安装 ​

Ably ​

手动安装 ​

客户端安装 ​

Reverb ​

手动安装 ​

Pusher Channels ​

手动安装 ​

使用现有客户端实例 ​

Ably ​

手动安装 ​

概念概述 ​

使用示例应用程序 ​

ShouldBroadcast 接口 ​

授权频道 ​

监听事件广播 ​

定义广播事件 ​

广播名称 ​

广播数据 ​

广播队列 ​

广播条件 ​

广播和数据库事务 ​

授权频道 ​

定义授权回调 ​

授权回调模型绑定 ​

授权回调身份验证 ​

定义频道类 ​

广播事件 ​

仅对其他人 ​

配置 ​

自定义连接 ​

匿名事件 ​

广播补救 ​

接收广播 ​

监听事件 ​

停止监听事件 ​

离开频道 ​

命名空间 ​

使用 React 或 Vue ​

连接到公开频道 ​

连接到在线频道 ​

存在频道 ​

授权存在频道 ​

加入存在频道 ​

广播到存在频道 ​

模型广播 ​

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

模型广播约定 ​

频道约定 ​

事件约定 ​

监听模型广播 ​

使用 React 或 Vue ​

客户端事件 ​

通知 ​

广播

介绍

支持的驱动程序

快速开始

下一步

服务器端安装

Reverb

手动安装

Pusher Channels

手动安装

Ably

手动安装

客户端安装

Reverb

手动安装

Pusher Channels

手动安装

使用现有客户端实例

Ably

手动安装

概念概述

使用示例应用程序

`ShouldBroadcast` 接口

授权频道

监听事件广播

定义广播事件

广播名称

广播数据

广播队列

广播条件

广播和数据库事务

授权频道

定义授权回调

授权回调模型绑定

授权回调身份验证

定义频道类

广播事件

仅对其他人

配置

自定义连接

匿名事件

广播补救

接收广播

监听事件

停止监听事件

离开频道

命名空间

使用 React 或 Vue

连接到公开频道

连接到在线频道

存在频道

授权存在频道

加入存在频道

广播到存在频道

模型广播

自定义模型广播事件创建

模型广播约定

频道约定

事件约定

监听模型广播

使用 React 或 Vue

客户端事件

通知