README

Laravel broadcast driver for the RelayStacks Conduit ecosystem — real-time events on shared hosting without Redis, Pusher, or long-running PHP.

Why Conduit

Most real-time broadcasting solutions require Redis, a paid service like Pusher, or the ability to run long-lived PHP processes. On shared cPanel hosting, none of these are available.

Conduit solves this by using a Unix domain socket to send events from PHP to a lightweight Node.js relay server that runs under Passenger. The Node server is a "dumb middleman" — Laravel owns all business logic, channel authorization, and presence tracking. No infrastructure beyond what cPanel already provides.

How It Works

Laravel Event (ShouldBroadcast)
    │
    ▼
ConduitBroadcaster (this package)
    │
    ▼
UnixSocketTransport (relaystacks/conduit-php)
    │  JSON + optional HMAC signing
    ▼
Unix domain socket (/home/user/laravel.sock)
    │
    ▼
conduit-echo (Node.js relay)
    │  Socket.IO
    ▼
Browser (Laravel Echo client)

Installation

composer require relaystacks/laravel-conduit

The service provider is auto-discovered — no manual registration needed.

Publish the config file:

php artisan vendor:publish --tag=conduit-config

Configuration

Environment Variables

Variable	Default	Description
CONDUIT_SOCKET_PATH	—	Absolute path to the Unix socket file
CONDUIT_SECRET	null	Shared HMAC-SHA256 secret (must match conduit-echo)
CONDUIT_TIMEOUT	2	Socket timeout in seconds

Broadcasting Config

Add the conduit connection to config/broadcasting.php:

'connections' => [
    'conduit' => [
        'driver'      => 'conduit',
        'socket_path' => env('CONDUIT_SOCKET_PATH'),
        'secret'      => env('CONDUIT_SECRET'),
        'timeout'     => env('CONDUIT_TIMEOUT', 2),
    ],
],

Set the default driver in .env:

BROADCAST_CONNECTION=conduit

Usage

Broadcast Events

Create events the standard Laravel way:

class OrderShipped implements ShouldBroadcast
{
    public function __construct(public Order $order) {}

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

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

Channel Types

Public channels — no authorization:

Broadcast::channel('news', function () {
    return true;
});

Private channels — require an authenticated user:

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

Presence channels — track who is online:

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

Guest Presence

Presence channels can accept unauthenticated users by using a nullable type hint:

Broadcast::channel('monitoring', function (?User $user) {
    if ($user) {
        return ['id' => $user->id, 'name' => $user->name];
    }

    $guestId = random_int(100000, 999999);

    return ['id' => 'guest-' . $guestId, 'name' => (string) $guestId];
});

Channels with a non-nullable User type hint will reject unauthenticated users automatically.

Channel Authorization

The conduit-echo Node server authorizes private and presence channels by POSTing to Laravel's /broadcasting/auth endpoint, forwarding the browser's session cookies.

Define channel callbacks in routes/channels.php:

// Private — must return true/false
Broadcast::channel('orders.{userId}', function (User $user, int $userId) {
    return $user->id === $userId;
});

// Presence — must return an array with user info
Broadcast::channel('chat.{roomId}', function (User $user, int $roomId) {
    return ['id' => $user->id, 'name' => $user->name];
});

API Reference

ConduitServiceProvider

Registered automatically via package auto-discovery. Merges the default config and registers the conduit broadcast driver with Laravel's BroadcastManager.

Published config tag: conduit-config

ConduitBroadcaster

Extends Illuminate\Broadcasting\Broadcasters\Broadcaster.

Method	Description
auth($request)	Authorize a channel subscription. Private channels require authentication; presence channels defer to the channel callback's type hint.
validAuthenticationResponse($request, $result)	Build the JSON auth response. For presence channels, includes channel_data with user_id and user_info.
broadcast(array $channels, $event, array $payload)	Send an event to channels via the transport. Failures are logged, not thrown.

Troubleshooting

Events not reaching the browser:

• Verify CONDUIT_SOCKET_PATH matches between PHP and Node configs
• Check that conduit-echo is running: GET /health should return {"status":"ok"}
• Check file permissions on the socket file (should be readable/writable by both PHP and Node processes)

Channel auth failing:

• Ensure /broadcasting/auth is accessible from localhost (the Node server POSTs to it)
• Verify cookies/session are being forwarded (check CONDUIT_AUTH_ENDPOINT in Node config)
• For presence channels, ensure the channel callback returns an array (not true)

Requirements

• PHP >= 8.1
• Laravel 10, 11, 12, or 13
• relaystacks/conduit-php (auto-required as a dependency)

License

MIT