Laravel Broadcasting Explained: Real-Time Events, Channels & WebSockets in Production

<?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\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;

// ShouldBroadcast tells Laravel to push this event through the broadcast driver.
// Using ShouldBroadcastNow would skip the queue — fine for low traffic, risky at scale.
class OrderShipped implements ShouldBroadcast
{
    use Dispatchable, InteractsWithSockets, SerializesModels;

    public function __construct(
        // public properties are automatically included in broadcastWith() by default
        public readonly Order $order
    ) {}

    /**
     * Define WHICH channel(s) this event broadcasts on.
     * A PrivateChannel requires the client to be authorised — crucial for user-specific data.
     */
    public function broadcastOn(): array
    {
        return [
            // Channel name uses the order owner's ID so each user only sees their own updates.
            new PrivateChannel('orders.' . $this->order->user_id),
        ];
    }

    /**
     * Control exactly what data goes to the browser.
     * Never rely on the default — always be explicit to avoid leaking sensitive model attributes.
     */
    public function broadcastWith(): array
    {
        return [
            'order_id'     => $this->order->id,
            'status'       => $this->order->status,
            'updated_at'   => $this->order->updated_at->toIso8601String(),
            // Deliberately omitting payment_token, internal_notes, etc.
        ];
    }

    /**
     * Override the default event name (App\Events\OrderShipped) with something
     * clean that your JavaScript can reference without knowing PHP namespaces.
     */
    public function broadcastAs(): string
    {
        return 'order.shipped';
    }
}

<?php

// routes/channels.php — this is your channel-level authorization firewall.
// Return true/false for private channels, return a user data array for presence channels.

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

/*
 |--------------------------------------------------------------------------
 | Private Channel: orders.{userId}
 |--------------------------------------------------------------------------
 | The {userId} wildcard is resolved and passed as a parameter.
 | The authenticated user object is always the first argument.
 | Return true only if the authenticated user owns this channel.
 */
Broadcast::channel('orders.{userId}', function ($authenticatedUser, int $userId) {
    // Strict integer comparison prevents type-juggling bypass (e.g. '1abc' == 1 in PHP)
    return $authenticatedUser->id === $userId;
});

/*
 |--------------------------------------------------------------------------
 | Presence Channel: chat-room.{roomId}
 |--------------------------------------------------------------------------
 | For presence channels, return an ARRAY of user data on success.
 | This array becomes the member info other subscribers can see.
 | Return false to deny access.
 */
Broadcast::channel('chat-room.{roomId}', function ($authenticatedUser, int $roomId) {
    $room = ChatRoom::find($roomId);

    // Guard: room must exist and user must be a member
    if (! $room || ! $room->hasMember($authenticatedUser)) {
        return false; // Echo will throw a subscription error on the client
    }

    // The array you return becomes the member object other users can inspect.
    // Only expose what other room members should actually see.
    return [
        'id'     => $authenticatedUser->id,
        'name'   => $authenticatedUser->display_name,
        'avatar' => $authenticatedUser->avatar_url,
    ];
});

/*
 |--------------------------------------------------------------------------
 | Class-based channel authorisation (cleaner for complex logic)
 |--------------------------------------------------------------------------
 | Instead of a closure, point to a class — Laravel will resolve it from the container,
 | meaning you can inject repositories, services, and cache layers.
 */
Broadcast::channel('orders.{userId}', \App\Broadcasting\OrderChannel::class);

<?php

// config/broadcasting.php — annotated production configuration
// Switch drivers by changing BROADCAST_DRIVER in your .env — zero code changes needed.

return [

    /*
    |--------------------------------------------------------------------------
    | Default Broadcaster
    |--------------------------------------------------------------------------
    | Options: 'reverb' | 'pusher' | 'ably' | 'redis' | 'log' | 'null'
    | Use 'log' locally to see broadcast output in your log file without a WebSocket server.
    | Use 'null' in automated tests to prevent real broadcasts.
    */
    'default' => env('BROADCAST_DRIVER', 'log'),

    'connections' => [

        /*
         * Laravel Reverb — first-party, zero extra runtime required.
         * Run: php artisan reverb:start (add --debug in development)
         * For production: run behind Nginx reverse-proxy with TLS termination.
         */
        'reverb' => [
            'driver'  => 'reverb',
            'key'     => env('REVERB_APP_KEY'),
            'secret'  => env('REVERB_APP_SECRET'),
            'app_id'  => env('REVERB_APP_ID'),
            'options' => [
                'host'   => env('REVERB_HOST', '0.0.0.0'),
                'port'   => env('REVERB_PORT', 8080),
                'scheme' => env('REVERB_SCHEME', 'https'), // always https in production
                // 'useTLS' handled by your Nginx/Caddy proxy — Reverb speaks plain HTTP internally
            ],
            // Reverb respects your queue connection for async broadcasts
            'client_options' => [],
        ],

        /*
         * Pusher — managed WebSocket-as-a-service.
         * Set PUSHER_* vars from your Pusher dashboard.
         */
        'pusher' => [
            'driver'  => 'pusher',
            'key'     => env('PUSHER_APP_KEY'),
            'secret'  => env('PUSHER_APP_SECRET'),
            'app_id'  => env('PUSHER_APP_ID'),
            'options' => [
                'cluster'   => env('PUSHER_APP_CLUSTER', 'mt1'),
                'encrypted' => true, // never set this to false in production
                /*
                 * Performance tuning: batch multiple broadcasts in one HTTP request.
 n                * Reduces RTT when firing many events in a single request lifecycle.
                 */
                'batch'     => true,
                'curl_options' => [
                    CURLOPT_CONNECTTIMEOUT => 3, // fail fast rather than blocking workers
                    CURLOPT_TIMEOUT        => 5,
                ],
            ],
        ],

        /*
         * Redis driver — pairs with Soketi or a compatible Pusher-protocol server.
         * Your Laravel app publishes to Redis; the WebSocket server consumes and forwards.
         */
        'redis' => [
            'driver'     => 'redis',
            'connection' => env('BROADCAST_REDIS_CONNECTION', 'default'),
            // Use a dedicated Redis connection for broadcasts to avoid HOL blocking
            // on your general-purpose Redis connection (cache, sessions, queues).
        ],

    ],

];

// resources/js/bootstrap.js (or your entry point)
// Full Echo setup for a Laravel Reverb backend with Sanctum SPA authentication.

import Echo from 'laravel-echo';
import Pusher from 'pusher-js'; // Reverb reuses the Pusher JS client under the hood

// Make Pusher available globally — Echo looks for window.Pusher
window.Pusher = Pusher;

window.Echo = new Echo({
    broadcaster: 'reverb', // or 'pusher' — same Pusher JS client either way
    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',
    enabledTransports: ['ws', 'wss'], // disable long-polling fallback for cleaner failure modes

    // CRITICAL for SPA/token auth: attach Bearer token to the channel auth request.
    // Without this, every private channel POST to /broadcasting/auth returns 401.
    authorizer: (channel) => ({
        authorize: (socketId, callback) => {
            window.axios.post('/broadcasting/auth', {
                socket_id:    socketId,
                channel_name: channel.name,
            }, {
                headers: {
                    Authorization: `Bearer ${localStorage.getItem('auth_token')}`,
                },
            })
            .then(response => callback(false, response.data))
            .catch(error  => callback(true, error));
        },
    }),
});


// --- Listening to a Private Channel ---
// resources/js/pages/OrderTracking.vue (or any component)

const currentUserId = window.authUser.id; // set by your Blade layout or API

// .private() triggers the /broadcasting/auth check automatically
window.Echo
    .private(`orders.${currentUserId}`)
    .listen('.order.shipped', (eventPayload) => {
        // The leading dot means we're using the broadcastAs() name, not the class name.
        // Without the dot Echo looks for App\Events\OrderShipped as the event name.
        console.log('Order update received:', eventPayload);
        // eventPayload = { order_id: 42, status: 'shipped', updated_at: '...' }

        updateOrderStatusInUI(eventPayload.order_id, eventPayload.status);
    });


// --- Presence Channel: Live Room Membership ---
window.Echo
    .join(`chat-room.${roomId}`)
    .here((members) => {
        // Called once on successful subscription with the full current member list
        // members = [{ id: 1, name: 'Alice', avatar: '...' }, { id: 2, name: 'Bob', avatar: '...' }]
        renderMemberList(members);
    })
    .joining((newMember) => {
        // Called whenever someone else subscribes to this channel
        addMemberToList(newMember);
        showToast(`${newMember.name} joined the room`);
    })
    .leaving((departedMember) => {
        // Called when a member's WebSocket disconnects or they explicitly unsubscribe
        removeMemberFromList(departedMember.id);
    })
    .listen('.new.message', (message) => {
        appendMessageToChat(message);
    });


// --- broadcastToOthers: Prevent Ghost Updates ---
// In your controller, instead of:
//   broadcast(new MessageSent($message));
// Use:
//   broadcast(new MessageSent($message))->toOthers();
//
// This tells the driver to exclude the socket ID that made this HTTP request,
// preventing the user who sent the message from receiving their own broadcast
// and double-rendering it alongside the optimistic UI update.
//
// Requires the X-Socket-ID header on your axios requests:

window.axios.defaults.headers.common['X-Socket-ID'] = window.Echo.socketId();
// Echo.socketId() is available only AFTER the connection is established.
// Wrap in Echo.connector.pusher.connection.bind('connected', () => { ... }) if needed.