# Laravel (https://sockudo.io/docs/server-sdks/laravel) > Use Sockudo as a native Laravel broadcasting driver with Echo-compatible channel auth, plus facade access to history, versioned messages, annotations, and push. `sockudo/laravel` is the official Laravel integration for Sockudo. It registers a `sockudo` broadcasting driver backed by the [PHP server SDK](/docs/server-sdks/php), binds that SDK in the service container, and exposes it through a facade. Existing Laravel broadcast events, channel authorization callbacks, and Laravel Echo keep working unchanged; trusted backend code can reach Sockudo-native APIs when it needs them. In Laravel, the package gives you: - A `sockudo` broadcasting connection for `ShouldBroadcast`, `ShouldBroadcastNow`, queued broadcasts, and `toOthers()`. - Private, presence, and encrypted private channel authorization through Laravel's `routes/channels.php`, plus user authentication. - The `Sockudo` facade and `Sockudo\SockudoInterface` binding, which proxy every PHP SDK method: publishing with idempotency keys, batches, webhook validation, channel state, history, presence history, versioned-message reads, annotations, and push. - Named connections for multiple Sockudo apps. - `sockudo:install` and `sockudo:check` Artisan commands. ## Install ```bash title="Terminal" composer require sockudo/laravel php artisan sockudo:install ``` The package requires PHP 8.2 or newer and Laravel 12 or 13, and depends on `sockudo/sockudo-php-server` `^2.2`. The service provider is auto-discovered. `sockudo:install` publishes `config/sockudo.php` (pass `--force` to overwrite an existing copy) and prints the environment variables to set. It warns when `routes/channels.php` is missing; private and presence channels need Laravel's broadcasting routes, so run `php artisan install:broadcasting` in that case. The package supplies the backend connection but never rewrites your route authorization. ## Configure the client Set credentials in `.env` or your secret manager: ```bash title=".env" BROADCAST_CONNECTION=sockudo SOCKUDO_APP_ID=app-id SOCKUDO_APP_KEY=app-key SOCKUDO_APP_SECRET=app-secret SOCKUDO_HOST=127.0.0.1 SOCKUDO_PORT=6001 SOCKUDO_SCHEME=http ``` Use `SOCKUDO_SCHEME=https` whenever the signed HTTP API crosses an untrusted network. Then confirm the configuration and API connectivity without printing credentials: ```bash title="Terminal" php artisan sockudo:check php artisan sockudo:check --config-only # validate config without contacting Sockudo php artisan sockudo:check --connection=sockudo-eu ``` Use `--config-only` in image builds where Sockudo is intentionally unreachable. The package adds a `sockudo` connection to `broadcasting.connections` at runtime unless your `config/broadcasting.php` already defines one with that name. The default connection comes from `config/sockudo.php`: ```php title="config/sockudo.php" $scheme = env('SOCKUDO_SCHEME', 'http'); return [ 'default' => env('BROADCAST_CONNECTION', 'null'), 'connection' => env('SOCKUDO_CONNECTION', 'sockudo'), 'broadcasting' => [ 'driver' => 'sockudo', 'key' => env('SOCKUDO_APP_KEY'), 'secret' => env('SOCKUDO_APP_SECRET'), 'app_id' => env('SOCKUDO_APP_ID'), 'options' => [ 'host' => env('SOCKUDO_HOST', '127.0.0.1'), 'port' => (int) env('SOCKUDO_PORT', $scheme === 'https' ? 443 : 6001), 'scheme' => $scheme, 'useTLS' => $scheme === 'https', 'path' => env('SOCKUDO_PATH', ''), 'timeout' => (int) env('SOCKUDO_TIMEOUT', 30), 'encryption_master_key_base64' => env('SOCKUDO_ENCRYPTION_MASTER_KEY_BASE64', ''), ], 'client_options' => [ 'connect_timeout' => (float) env('SOCKUDO_CONNECT_TIMEOUT', 5), ], ], ]; ``` | Environment variable | Config key | Default | Description | | --- | --- | --- | --- | | `BROADCAST_CONNECTION` | `sockudo.default` | `null` | Set to `sockudo` to broadcast Laravel events through Sockudo. Used only when `broadcasting.default` is not already configured. | | `SOCKUDO_CONNECTION` | `sockudo.connection` | `sockudo` | Broadcasting connection used by the facade, `SockudoInterface`, and `sockudo:check`. | | `SOCKUDO_APP_ID` | `app_id` | — | Required. | | `SOCKUDO_APP_KEY` | `key` | — | Required. | | `SOCKUDO_APP_SECRET` | `secret` | — | Required. Server-side only. | | `SOCKUDO_HOST` | `options.host` | `127.0.0.1` | HTTP API host. | | `SOCKUDO_PORT` | `options.port` | `6001`, or `443` when the scheme is `https` | HTTP API port. | | `SOCKUDO_SCHEME` | `options.scheme`, `options.useTLS` | `http` | `https` also sets `useTLS`. | | `SOCKUDO_PATH` | `options.path` | `''` | Path prefix for a reverse proxy. | | `SOCKUDO_TIMEOUT` | `options.timeout` | `30` | Per-request timeout in seconds; also applied to the Guzzle client. | | `SOCKUDO_CONNECT_TIMEOUT` | `client_options.connect_timeout` | `5` | Guzzle connect timeout in seconds. | | `SOCKUDO_ENCRYPTION_MASTER_KEY_BASE64` | `options.encryption_master_key_base64` | `''` | Base64 of a 32-byte key for `private-encrypted-` channels. | | — | `jsonp` | `false` | Allow JSONP `callback` responses from the auth endpoints. | Config keys other than `sockudo.*` live under `broadcasting.connections.sockudo`. Everything under `options` is passed to the PHP SDK constructor, so SDK options such as `auto_idempotency_key` can be added there; see the [PHP option table](/docs/server-sdks/php#configure-the-client). `client_options` is passed to `new GuzzleHttp\Client(...)`. Resolving a connection that is missing `key`, `secret`, or `app_id` throws `InvalidArgumentException`. Restart long-lived queue workers after changing cached configuration. The app secret must stay on the server. It signs every HTTP API call and every channel and user auth response, so anyone holding it can publish to any channel and impersonate any user. Never expose `SOCKUDO_APP_SECRET` to Vite or JavaScript; only the key, host, port, and scheme belong in `VITE_` variables. ### Multiple Sockudo apps Define additional `'driver' => 'sockudo'` entries in `config/broadcasting.php`, each with its own credentials, host, TLS options, and `client_options`, then select one explicitly: ```php title="app/Services/EuOrders.php" use Sockudo\Laravel\Facades\Sockudo; $client = Sockudo::connection('sockudo-eu'); $client->trigger('orders', 'order.updated', ['id' => 'ord-123']); ``` Clients are created once per connection name and reused. Inject `Sockudo\SockudoInterface` when constructor injection is preferable; it resolves the connection named by `SOCKUDO_CONNECTION`. ## Publish an event Laravel's broadcast events work without Sockudo-specific interfaces: ```php title="app/Events/OrderUpdated.php" orderId}"); } public function broadcastAs(): string { return 'order.updated'; } } ``` ```php title="app/Http/Controllers/OrderController.php" broadcast(new OrderUpdated($order->id, 'paid'))->toOthers(); ``` `ShouldBroadcast` events are queued; `ShouldBroadcastNow` sends them during the request. `toOthers()` excludes the browser connection that made the request: Echo sends its socket ID in the `X-Socket-ID` header, and the driver forwards it as `socket_id` so that client does not receive an echo of a change it already applied. For direct control over the payload, response, or idempotency key, publish through the facade: ```php title="app/Actions/PublishOrderPaid.php" use Sockudo\Laravel\Facades\Sockudo; $result = Sockudo::trigger('private-orders.' . $order->id, 'order.paid', [ 'id' => $order->id, 'status' => 'paid', ], [ 'idempotency_key' => "order.paid:{$order->tenant_id}:{$order->id}:v{$order->version}", ]); ``` The facade uses Sockudo channel names directly, so add the `private-` or `presence-` prefix that Laravel's channel classes add for you. `trigger` returns the decoded API response as an object. To exclude the originating connection, add `'socket_id' => $socketId` with the value Echo sent in the `X-Socket-ID` header. ## Publish to many channels or in a batch Return several channels from `broadcastOn()` to publish one event to all of them. The driver publishes in chunks of 100 channels per API call, so larger lists become several requests. ```php title="app/Events/OrderUpdated.php" public function broadcastOn(): array { return [ new PrivateChannel("tenants.{$this->tenantId}.orders"), new PrivateChannel("users.{$this->customerId}.orders"), ]; } ``` Through the facade, `trigger` accepts up to 100 channel names, and `triggerBatch` sends different events in one request: ```php title="app/Actions/PublishOrderBatch.php" use Sockudo\Laravel\Facades\Sockudo; Sockudo::triggerBatch([ [ 'channel' => 'private-orders.124', 'name' => 'order.created', 'data' => ['id' => 'ord_124'], 'idempotency_key' => 'order.created:tenant-42:ord_124:v1', ], [ 'channel' => 'private-users.7', 'name' => 'order.receipt', 'data' => ['id' => 'ord_124'], ], ]); ``` Server defaults from `[event_limits]`: | Limit | Server default | | --- | --- | | Channels per event (`max_channels_at_once`) | `100` | | Events per batch (`max_batch_size`) | `10` | | Payload size (`max_payload_in_kb`) | `100` KB | | Event and channel name length (`max_name_length`) | `200` | ## Idempotency and retries A timeout does not tell you whether the server published the event. Retrying without an idempotency key can deliver it twice; retrying with the same key lets the server recognise the duplicate. How the server handles keys: - The key can be sent as the `idempotency_key` body field or the `X-Idempotency-Key` header. When both are present, the body field wins. - The `[idempotency]` defaults are `enabled = true`, `ttl_seconds = 120`, and `max_key_length = 128`. Empty keys are rejected. - A duplicate within the TTL returns the original cached response with status `200` and does not publish again. - For batches, `X-Idempotency-Key` identifies the whole batch and a per-item `idempotency_key` identifies only that event. The two key domains do not collide. - If the coordination backend is unavailable, the server returns `503 service_unavailable`. A concurrent retry while the first attempt is still in flight gets `503 backpressure` with `Retry-After: 1`. Retry both with the same key. How keys flow through Laravel: - Broadcast events cannot carry an idempotency key. The PHP SDK attaches an auto-generated key to each API call and retries `5xx` responses with it, up to three attempts. When the broadcast job itself is retried by the queue, the event is published again with a new key, so a job that timed out after the server published can deliver twice. - For events that must not duplicate, publish from your own queued job with `Sockudo::trigger` and an explicit `idempotency_key`, or per-item keys in `Sockudo::triggerBatch`. The same key on every job attempt makes queue retries safe. `triggerBatch` does not send a batch-level header. ```php title="app/Jobs/PublishOrderPaid.php" public function handle(): void { Sockudo::trigger("private-orders.{$this->orderId}", 'order.paid', $this->payload, [ // Stable across every attempt of this job. 'idempotency_key' => "order.paid:{$this->tenantId}:{$this->orderId}:v{$this->version}", ]); } ``` A key identifies a logical operation such as `order.created:tenant-42:order-123:v1`, not an HTTP attempt or a job attempt. Never reuse a key for a different payload: within the TTL the server returns the first response and silently drops the new event. ## Authorize private and presence channels When Echo subscribes to a private or presence channel, it asks Laravel's `/broadcasting/auth` route for a signed auth response. The driver signs the response only after your channel callback returns a truthy value; signing is not authorization. Your callback decides whether this user may join this exact channel, and for presence channels the identity comes from the authenticated user, never from the request. ```php title="routes/channels.php" use App\Models\Order; use App\Models\Room; use App\Models\User; use Illuminate\Support\Facades\Broadcast; Broadcast::channel('orders.{order}', function (User $user, Order $order) { return $user->can('view', $order); }); Broadcast::channel('rooms.{room}', function (User $user, Room $room) { if (!$user->can('join', $room)) { return false; } // Presence: the array becomes user_info for other members. return ['name' => $user->name]; }); ``` The driver handles the request parsing and response for you: it reads the form-encoded `socket_id` and `channel_name`, rejects guarded channels for unauthenticated users with `403`, runs your callback, and returns JSON. For `presence-` channels it uses the user's `getAuthIdentifierForBroadcasting()` (or `getAuthIdentifier()`) as `user_id` and the array your callback returns as `user_info`. Laravel only checks that a callback exists and returns a truthy value. A callback that returns `true` for every user lets every signed-in user join that channel. Check tenant and resource ownership in each callback. ### Connect Laravel Echo Laravel Echo uses its Pusher connector for Sockudo's Protocol V1 connection: ```js title="resources/js/echo.js" window.Pusher = Pusher; window.Echo = new Echo({ broadcaster: 'pusher', key: import.meta.env.VITE_SOCKUDO_APP_KEY, wsHost: import.meta.env.VITE_SOCKUDO_HOST, wsPort: Number(import.meta.env.VITE_SOCKUDO_PORT ?? 6001), wssPort: Number(import.meta.env.VITE_SOCKUDO_PORT ?? 443), forceTLS: (import.meta.env.VITE_SOCKUDO_SCHEME ?? 'https') === 'https', enabledTransports: ['ws', 'wss'], }); ``` Protocol V2 features such as recovery, rewind, tag filters, delta compression, and versioned-message projections need a Sockudo-native realtime client rather than Laravel Echo. See [Client SDKs](/docs/clients). ### User authentication User authentication binds a connection to a user ID for user-targeted events and connection termination. Tell Laravel how to describe the signed-in user, and expose the `/broadcasting/user-auth` route with `Broadcast::userRoutes()` if your app does not already register it: ```php title="app/Providers/AppServiceProvider.php" use Illuminate\Support\Facades\Broadcast; public function boot(): void { Broadcast::resolveAuthenticatedUserUsing(fn ($request) => $request->user() ? [ 'id' => (string) $request->user()->id, 'name' => $request->user()->name, ] : null); } ``` The driver passes the array to the SDK's `authenticateUser`, which requires a non-empty `id`. Returning an `Arrayable` also works. Send events to a signed-in user with `Sockudo::sendToUser($userId, $event, $data)`. ### Encrypted channels Set `SOCKUDO_ENCRYPTION_MASTER_KEY_BASE64` to a base64-encoded 32-byte key (for example from `openssl rand -base64 32`). Laravel's `PrivateEncryptedChannel` maps to `private-encrypted-` channels; the driver signs them like other private channels and adds the per-channel shared secret, and the SDK encrypts event data before publishing. Subscribe with Echo's `encryptedPrivate()`. Broadcast each encrypted event to a single encrypted channel: the SDK rejects events that mix encrypted and unencrypted channels, and encrypts the payload with the first channel's key, so other encrypted channels in the same event could not decrypt it. ### Terminate user connections ```php title="app/Actions/RevokeUserAccess.php" use Sockudo\Laravel\Facades\Sockudo; Sockudo::terminateUserConnections((string) $user->id); // disconnect Sockudo::forceReconnectUser((string) $user->id); // close with 4200 so clients re-authorize ``` ## Validate webhooks The package does not register a webhook route. Validate deliveries with the SDK's `webhook` method through the facade. Sockudo signs the exact request body bytes with HMAC-SHA256, so pass `$request->getContent()`, never re-encoded JSON from `$request->all()`. ```php title="routes/web.php" use App\Jobs\ProcessSockudoWebhookEvent; use Illuminate\Http\Request; use Illuminate\Support\Facades\Route; use Sockudo\Laravel\Facades\Sockudo; use Sockudo\SockudoException; Route::post('/sockudo/webhooks', function (Request $request) { try { $webhook = Sockudo::webhook([ // The SDK looks up these exact header names. 'X-Pusher-Key' => (string) $request->header('X-Pusher-Key', ''), 'X-Pusher-Signature' => (string) $request->header('X-Pusher-Signature', ''), ], $request->getContent()); } catch (SockudoException) { abort(401); } foreach ($webhook->get_events() as $event) { ProcessSockudoWebhookEvent::dispatch((array) $event, $webhook->get_time_ms()); } return response()->noContent(); }); ``` Webhooks carry no CSRF token, so exclude the route in `bootstrap/app.php`: ```php title="bootstrap/app.php" ->withMiddleware(function (Middleware $middleware) { $middleware->validateCsrfTokens(except: ['sockudo/webhooks']); }) ``` `webhook` throws `SockudoException` when the key or signature does not match or the body is not valid JSON, and decrypts encrypted-channel events when the master key is configured. Respond quickly and process in a queued job: Sockudo retries failed deliveries, so make the handler idempotent. ## Channel state and history ```php title="app/Services/OrderPresence.php" use Sockudo\Laravel\Facades\Sockudo; $info = Sockudo::getChannelInfo('presence-rooms.7', ['info' => 'user_count']); $channels = Sockudo::getChannels(['filter_by_prefix' => 'presence-']); $members = Sockudo::getPresenceUsers('presence-rooms.7'); $page = Sockudo::getChannelHistory('private-orders.123', [ 'limit' => 50, 'direction' => 'newest_first', ]); if ($page->has_more) { $next = Sockudo::getChannelHistory('private-orders.123', ['cursor' => $page->next_cursor]); } $transitions = Sockudo::getPresenceHistory('presence-rooms.7', ['limit' => 100]); $snapshot = Sockudo::getPresenceSnapshot('presence-rooms.7', ['at_time_ms' => $timestampMs]); ``` Cursors are opaque; pass `next_cursor` back unchanged. Use Sockudo channel names, including the `private-` or `presence-` prefix. Rate-limit and authorize any application endpoint that exposes history to users. See [History and recovery](/docs/server/history-recovery). ## Versioned messages and annotations The facade exposes the PHP SDK's Protocol V2 helpers for reading versioned messages and managing annotations: ```php title="app/Services/OrderMessages.php" use Sockudo\Laravel\Facades\Sockudo; $message = Sockudo::getMessage('orders', $messageSerial); $versions = Sockudo::getMessageVersions('orders', $messageSerial, ['limit' => 20]); $annotation = Sockudo::publishAnnotation('orders', $messageSerial, [ 'type' => 'reaction', 'name' => 'confirmed', ]); $annotations = Sockudo::listAnnotations('orders', $messageSerial); Sockudo::deleteAnnotation('orders', $messageSerial, $annotation->annotationSerial); ``` In PHP SDK `2.2.0`, `updateMessage`, `deleteMessage`, and `appendMessage` do not JSON-encode their parameters and fail with a `TypeError`. Send mutations through the facade's generic `post` helper with a JSON-encoded body until the SDK is fixed. ```php title="app/Services/OrderMessages.php" Sockudo::post( '/channels/orders/messages/' . rawurlencode($messageSerial) . '/update', json_encode([ 'data' => json_encode(['status' => 'paid']), 'op_id' => 'order.paid:ord-123:v4', ], JSON_THROW_ON_ERROR), ); ``` The same pattern works for `/append` and `/delete`. Paths exclude the `/apps/` prefix, and `Sockudo::get` and `Sockudo::delete` cover other endpoints without a typed helper. See [Mutable messages](/docs/server/mutable-messages). ## Push notifications Every PHP SDK push helper is available through the facade: ```php title="app/Actions/NotifyOrderPacked.php" use Sockudo\Laravel\Facades\Sockudo; $accepted = Sockudo::publishPush([ 'recipients' => [['type' => 'channel', 'channel' => 'orders']], 'payload' => ['title' => 'Order updated', 'body' => 'Order ord-123 is packed'], 'publishId' => 'order-packed:ord-123:v4', ]); $status = Sockudo::getPublishStatus($accepted->publishId); ``` `publishPush` returns an admission record (`publishId`, `status`, `expectedRecipients`), not a delivery result. Check `getPublishStatus` later, for example from a scheduled job, and reuse the same `publishId` on retries. Device registrations, channel subscriptions, credentials, `publishPushBatch`, `schedulePush`, and `cancelScheduledPush` are listed on the [PHP page](/docs/server-sdks/php#push-notifications). For iOS 18 Live Activity broadcast channels, use `createApnsLiveActivityChannel`, `getApnsLiveActivityChannel`, `listApnsLiveActivityChannels`, and `deleteApnsLiveActivityChannel`. See [Push notifications](/docs/server/push-notifications) and [Apple Live Activities](/docs/server/apple-live-activities). ## Errors and timeouts Failures surface differently depending on the path: - Broadcast events: any publish failure becomes `Illuminate\Broadcasting\BroadcastException` with the message `Sockudo publish failed.` The original exception is deliberately not chained, because transport errors can contain signed URLs or response bodies. Queued broadcasts follow your queue's retry settings; run `php artisan sockudo:check` to diagnose connectivity or credentials. - Facade and `SockudoInterface` calls: the PHP SDK's exceptions propagate unchanged. `Sockudo\ApiErrorException` carries the HTTP status in `getCode()` (`0` for connection failures and timeouts); `Sockudo\SockudoException` signals invalid input caught before sending. - Missing connection or credentials: `InvalidArgumentException` when the connection is resolved. - Auth endpoints: `AccessDeniedHttpException` (`403`) when the user is not allowed on the channel. `SOCKUDO_TIMEOUT` (default 30 seconds) bounds each request and `SOCKUDO_CONNECT_TIMEOUT` (default 5 seconds) bounds connection setup. Keep both below your queue job's timeout. ```php title="app/Jobs/PublishOrderPaid.php" use Sockudo\ApiErrorException; use Sockudo\Laravel\Facades\Sockudo; public function handle(): void { try { Sockudo::trigger("private-orders.{$this->orderId}", 'order.paid', $this->payload, [ 'idempotency_key' => $this->idempotencyKey, ]); } catch (ApiErrorException $error) { $status = $error->getCode(); if ($status === 0 || $status === 429 || $status >= 500) { $this->release(5); // retry later with the same key return; } $this->fail($error); // 400, 401, 403, 413: retrying will not help } } ``` Retry network errors, timeouts, `429`, and `5xx` responses with backoff. Do not retry `400`, `401`, `403`, or `413`. Never log signed URLs, `SOCKUDO_APP_SECRET`, or raw request and response bodies. Test public, private, presence, encrypted, `toOthers()`, and queued broadcast flows against a staging Sockudo server, and confirm that queue workers pick up configuration changes after a restart. ## Next steps - [PHP server SDK](/docs/server-sdks/php): Every method the facade proxies, with options and defaults. - [Authentication](/docs/getting-started/authentication): How clients request private, presence, and user auth from your backend. - [Webhooks](/docs/server/webhooks): Webhook events, delivery, retries, and configuration. - [History and recovery](/docs/server/history-recovery): Durable history, cursors, and two-tier recovery.