廣播 - Knowledge of Laravel

廣播是什麼

透過 WebSocket，伺服器可以將資料即時傳送給客戶端。 Laravel 的廣播機制會將伺服器端的事件透過 WebSocket 傳送到前端的 JavaScript。例如，當訂單狀態改變時，即使不重新載入頁面也能立即在瀏覽器上顯示更新。 Laravel 廣播的強項在於伺服器端的事件名稱與資料，可以原封不動地共享給客戶端。

廣播是建立在 Laravel 的事件系統之上的。建議先理解事件與監聽器的基本概念。

設定

在新的 Laravel 應用程式中，廣播預設為停用。請使用 install:broadcasting Artisan 指令啟用。

php artisan install:broadcasting

執行此指令後，會提示你選擇要使用的廣播服務，並產生 config/broadcasting.php 與 routes/channels.php。

Laravel Reverb

在 Laravel 11 以後，推薦使用官方的 WebSocket 伺服器 Laravel Reverb。 Reverb 屬於自架方案，無須額外的外部服務就能實現即時通訊。

安裝

在 install:broadcasting 指令加上 --reverb 選項，即可一次完成 Reverb 所需 Composer 套件與 NPM 套件的安裝，以及 .env 設定。

php artisan install:broadcasting --reverb

若要手動安裝，可先透過 Composer 加入套件，再執行安裝指令。

composer require laravel/reverb

php artisan reverb:install

`.env` 的主要設定值

BROADCAST_CONNECTION=reverb

REVERB_APP_ID=my-app-id
REVERB_APP_KEY=my-app-key
REVERB_APP_SECRET=my-app-secret
REVERB_HOST=localhost
REVERB_PORT=8080
REVERB_SCHEME=http

VITE_REVERB_APP_KEY="${REVERB_APP_KEY}"
VITE_REVERB_HOST="${REVERB_HOST}"
VITE_REVERB_PORT="${REVERB_PORT}"
VITE_REVERB_SCHEME="${REVERB_SCHEME}"

啟動 Reverb 伺服器

php artisan reverb:start

在正式環境中，請透過 Supervisor 等程序管理器以常駐程式方式管理。

廣播事件是透過佇列處理的。除了 Reverb 伺服器外，也需要另外啟動佇列 worker。

php artisan queue:work

建立廣播事件

產生事件類別

php artisan make:event OrderShipmentStatusUpdated

在產生的事件類別中實作 ShouldBroadcast 介面。

<?php

namespace App\Events;

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

class OrderShipmentStatusUpdated implements ShouldBroadcast
{
    use InteractsWithSockets, SerializesModels;

    public function __construct(
        public Order $order,
    ) {}

    /**
     * 回傳要廣播事件的頻道
     */
    public function broadcastOn(): Channel
    {
        return new PrivateChannel('orders.' . $this->order->id);
    }
}

只要實作 ShouldBroadcast，事件被觸發時就會自動透過佇列進行廣播。

自訂廣播資料

預設情況下，事件類別的所有 public 屬性都會包含在廣播的 payload 中。若要限縮傳送的資料，請定義 broadcastWith 方法。

public function broadcastWith(): array
{
    return [
        'order_id' => $this->order->id,
        'status'   => $this->order->status,
    ];
}

自訂廣播名稱

預設情況下，類別名稱即為事件名稱。可透過 broadcastAs 方法指定自訂名稱。

public function broadcastAs(): string
{
    return 'order.status.updated';
}

前端監聽時，請在名稱前加上 . 以停用應用程式的命名空間前綴。

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

頻道類型

頻道	類別	說明
Public	`Channel`	無須認證，任何人都可訂閱
Private	`PrivateChannel`	僅限已認證使用者，需要授權邏輯
Presence	`PresenceChannel`	Private 的延伸，可取得頻道成員清單

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

// Public 頻道
public function broadcastOn(): Channel
{
    return new Channel('posts');
}

// Private 頻道
public function broadcastOn(): Channel
{
    return new PrivateChannel('orders.' . $this->order->id);
}

// Presence 頻道
public function broadcastOn(): Channel
{
    return new PresenceChannel('rooms.' . $this->room->id);
}

若要對多個頻道廣播，請以陣列形式回傳。

public function broadcastOn(): array
{
    return [
        new PrivateChannel('orders.' . $this->order->id),
        new Channel('admin.orders'),
    ];
}

頻道授權

Private 頻道與 Presence 頻道會在訂閱前於伺服器端進行授權檢查。

routes/channels.php

透過 install:broadcasting 指令產生的 routes/channels.php 中定義授權 callback。

use App\Models\Order;
use App\Models\User;
use Illuminate\Support\Facades\Broadcast;

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

callback 的第 1 個參數是已認證的使用者，之後的參數則對應到頻道名稱中的萬用字元。回傳 true 或 truthy 值代表授權成功，回傳 false 則會被拒絕。

也可以使用路由模型繫結。若將頻道名稱設為 orders.{order}，則會傳入 Order 模型實例。

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

透過頻道類別進行授權

當頻道變多時，可透過頻道類別加以整理。

php artisan make:channel OrderChannel

<?php

namespace App\Broadcasting;

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

class OrderChannel
{
    public function join(User $user, Order $order): bool
    {
        return $user->id === $order->user_id;
    }
}

在 routes/channels.php 中註冊。

use App\Broadcasting\OrderChannel;

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

觸發事件

實作了 ShouldBroadcast 的事件與一般事件的觸發方式相同。

use App\Events\OrderShipmentStatusUpdated;

OrderShipmentStatusUpdated::dispatch($order);

若只想廣播給自己以外的其他使用者，請使用 toOthers。

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

使用 toOthers 時，事件類別必須使用 InteractsWithSockets trait。

前端接收

設定 Laravel Echo

使用 Reverb 時，請在 resources/js/bootstrap.js 中設定 Echo 實例。

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

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

監聽事件

// Public 頻道
Echo.channel('posts')
    .listen('PostPublished', (e) => {
        console.log(e.post);
    });

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

// Presence 頻道
Echo.join(`rooms.${roomId}`)
    .here((users) => {
        console.log('目前的成員：', users);
    })
    .joining((user) => {
        console.log(user.name, '加入了頻道');
    })
    .leaving((user) => {
        console.log(user.name, '離開了頻道');
    })
    .listen('MessagePosted', (e) => {
        console.log(e.message);
    });

使用 React / Vue Hook

若你使用 React 或 Vue 的入門套件，可以透過專屬 Hook 讓程式更精簡。

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

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

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

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

useEcho Hook 會在元件卸載時自動退出頻道。

在建置前端資源之前，請確認 .env 內的 VITE_REVERB_* 變數已正確設定。

npm run build

實戰範例：訂單狀態即時更新

啟用廣播

php artisan install:broadcasting --reverb

啟動 Reverb 伺服器與佇列 worker。

php artisan reverb:start
php artisan queue:work

建立事件類別

php artisan make:event OrderShipmentStatusUpdated

編輯 app/Events/OrderShipmentStatusUpdated.php。

<?php

namespace App\Events;

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

class OrderShipmentStatusUpdated implements ShouldBroadcast
{
    use InteractsWithSockets, SerializesModels;

    public function __construct(
        public Order $order,
    ) {}

    public function broadcastOn(): Channel
    {
        return new PrivateChannel('orders.' . $this->order->id);
    }

    public function broadcastWith(): array
    {
        return [
            'order_id' => $this->order->id,
            'status'   => $this->order->status,
        ];
    }
}

定義頻道授權

在 routes/channels.php 加入授權邏輯。

use App\Models\Order;
use App\Models\User;
use Illuminate\Support\Facades\Broadcast;

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

觸發事件

在更新訂單狀態的控制器或 Job 中觸發事件。

use App\Events\OrderShipmentStatusUpdated;

$order->update(['status' => 'shipped']);

OrderShipmentStatusUpdated::dispatch($order);

前端進行監聽

在 Blade 樣板中使用內嵌 script，或於 React / Vue 元件中接收。

Echo.private(`orders.${orderId}`)
    .listen('OrderShipmentStatusUpdated', (e) => {
        document.getElementById('status').textContent = e.status;
    });

下一步

Laravel Reverb

進一步了解 Reverb 伺服器的設定、正式環境維運與擴展。

佇列與工作

廣播是透過佇列處理的，請確認佇列的設定與運行方式。

事件與監聽器

進一步學習作為廣播基礎的 Laravel 事件系統。

​廣播是什麼

​設定

​Laravel Reverb

​安裝

​.env 的主要設定值

​啟動 Reverb 伺服器

​建立廣播事件

​產生事件類別

​自訂廣播資料

​自訂廣播名稱

​頻道類型

​頻道授權

​routes/channels.php

​透過頻道類別進行授權

​觸發事件

​前端接收

​設定 Laravel Echo

​監聽事件

​使用 React / Vue Hook

​實戰範例：訂單狀態即時更新

​下一步

Laravel Reverb

佇列與工作

事件與監聽器

廣播是什麼

設定

Laravel Reverb

安裝

`.env` 的主要設定值

啟動 Reverb 伺服器

建立廣播事件

產生事件類別

自訂廣播資料

自訂廣播名稱

頻道類型

頻道授權

routes/channels.php

透過頻道類別進行授權

觸發事件

前端接收

設定 Laravel Echo

監聽事件

使用 React / Vue Hook

實戰範例：訂單狀態即時更新

下一步