Laravel

Use Sockudo as a native Laravel broadcasting driver with Echo-compatible channel auth, plus facade access to history, versioned messages, annotations, and push.

9 min read
View .mdEdit on GitHub

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 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

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:

.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:

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:

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 variableConfig keyDefaultDescription
BROADCAST_CONNECTIONsockudo.defaultnullSet to sockudo to broadcast Laravel events through Sockudo. Used only when broadcasting.default is not already configured.
SOCKUDO_CONNECTIONsockudo.connectionsockudoBroadcasting connection used by the facade, SockudoInterface, and sockudo:check.
SOCKUDO_APP_IDapp_id—Required.
SOCKUDO_APP_KEYkey—Required.
SOCKUDO_APP_SECRETsecret—Required. Server-side only.
SOCKUDO_HOSToptions.host127.0.0.1HTTP API host.
SOCKUDO_PORToptions.port6001, or 443 when the scheme is httpsHTTP API port.
SOCKUDO_SCHEMEoptions.scheme, options.useTLShttphttps also sets useTLS.
SOCKUDO_PATHoptions.path''Path prefix for a reverse proxy.
SOCKUDO_TIMEOUToptions.timeout30Per-request timeout in seconds; also applied to the Guzzle client.
SOCKUDO_CONNECT_TIMEOUTclient_options.connect_timeout5Guzzle connect timeout in seconds.
SOCKUDO_ENCRYPTION_MASTER_KEY_BASE64options.encryption_master_key_base64''Base64 of a 32-byte key for private-encrypted- channels.
—jsonpfalseAllow 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:

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:

app/Events/OrderUpdated.php
<?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';
}
}
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:

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.

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:

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]:

LimitServer 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.
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}",
]);
}

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.

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.

Connect Laravel Echo

Laravel Echo uses its Pusher connector for Sockudo’s Protocol V1 connection:

resources/js/echo.js
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:

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

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().

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:

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

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.

Versioned messages and annotations

The facade exposes the PHP SDK’s Protocol V2 helpers for reading versioned messages and managing annotations:

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);
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/<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:

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.

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\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.

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.

Next steps