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, 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
sockudobroadcasting connection forShouldBroadcast,ShouldBroadcastNow, queued broadcasts, andtoOthers(). - Private, presence, and encrypted private channel authorization through Laravel’s
routes/channels.php, plus user authentication. - The
Sockudofacade andSockudo\SockudoInterfacebinding, 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:installandsockudo:checkArtisan commands.
Install
composer require sockudo/laravelphp artisan sockudo:installThe 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:
BROADCAST_CONNECTION=sockudo
SOCKUDO_APP_ID=app-idSOCKUDO_APP_KEY=app-keySOCKUDO_APP_SECRET=app-secretSOCKUDO_HOST=127.0.0.1SOCKUDO_PORT=6001SOCKUDO_SCHEME=httpUse SOCKUDO_SCHEME=https whenever the signed HTTP API crosses an untrusted network. Then confirm
the configuration and API connectivity without printing credentials:
php artisan sockudo:checkphp artisan sockudo:check --config-only # validate config without contacting Sockudophp artisan sockudo:check --connection=sockudo-euUse --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:
$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.
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:
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
namespace App\Events;
use Illuminate\Broadcasting\InteractsWithSockets;use Illuminate\Broadcasting\PrivateChannel;use Illuminate\Contracts\Broadcasting\ShouldBroadcast;
final class OrderUpdated implements ShouldBroadcast{ use InteractsWithSockets;
public function __construct( public readonly string $orderId, public readonly string $status, ) {}
public function broadcastOn(): PrivateChannel { return new PrivateChannel("orders.{$this->orderId}"); }
public function broadcastAs(): string { return 'order.updated'; }}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:
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.
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:
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_keybody field or theX-Idempotency-Keyheader. When both are present, the body field wins. - The
[idempotency]defaults areenabled = true,ttl_seconds = 120, andmax_key_length = 128. Empty keys are rejected. - A duplicate within the TTL returns the original cached response with status
200and does not publish again. - For batches,
X-Idempotency-Keyidentifies the whole batch and a per-itemidempotency_keyidentifies 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 gets503 backpressurewithRetry-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
5xxresponses 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::triggerand an explicitidempotency_key, or per-item keys inSockudo::triggerBatch. The same key on every job attempt makes queue retries safe.triggerBatchdoes not send a batch-level header.
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}", ]);}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.
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.
Connect Laravel Echo
Laravel Echo uses its Pusher connector for Sockudo’s Protocol V1 connection:
import Echo from 'laravel-echo';import Pusher from 'pusher-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.
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:
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
use Sockudo\Laravel\Facades\Sockudo;
Sockudo::terminateUserConnections((string) $user->id); // disconnectSockudo::forceReconnectUser((string) $user->id); // close with 4200 so clients re-authorizeValidate 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().
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:
->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
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.
Versioned messages and annotations
The facade exposes the PHP SDK’s Protocol V2 helpers for reading versioned messages and managing annotations:
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);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/<app_id> prefix, and
Sockudo::get and Sockudo::delete cover other endpoints without a typed helper. See
Mutable messages.
Push notifications
Every PHP SDK push helper is available through the facade:
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.
For iOS 18 Live Activity broadcast channels, use createApnsLiveActivityChannel,
getApnsLiveActivityChannel, listApnsLiveActivityChannels, and
deleteApnsLiveActivityChannel. See Push notifications and
Apple Live Activities.
Errors and timeouts
Failures surface differently depending on the path:
- Broadcast events: any publish failure becomes
Illuminate\Broadcasting\BroadcastExceptionwith the messageSockudo 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; runphp artisan sockudo:checkto diagnose connectivity or credentials. - Facade and
SockudoInterfacecalls: the PHP SDK’s exceptions propagate unchanged.Sockudo\ApiErrorExceptioncarries the HTTP status ingetCode()(0for connection failures and timeouts);Sockudo\SockudoExceptionsignals invalid input caught before sending. - Missing connection or credentials:
InvalidArgumentExceptionwhen 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.
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.