Download the PHP package belysh/laravel-socket-bridge without Composer

Socket Bridge for Laravel

Send Laravel events and notifications over WebSockets, authorize subscriptions with channel policies, and handle client commands in PHP. A bundled NestJS / Socket.IO gateway manages connections; Redis Streams carry messages between the gateway and Laravel.

Each Laravel application runs its own bridge, with support for multiple gateway replicas.

Deployment

Requirements

• Laravel 13, PHP 8.3+, and MySQL, PostgreSQL or SQLite.
• Redis 7+ with a Laravel Redis client (phpredis or predis/predis). Redis Cluster is not supported.
• macOS or Linux for native development; Docker or WSL2 on Windows.

Installation

The installer configures the socketio broadcaster and lets you choose how to run the gateway:

• Native — uses your Laravel Redis connection and prepares Node 24 automatically.
• Docker — requires Docker Compose v2; uses an existing Redis or creates a dedicated Redis service.

Start the gateway and workers alongside your Laravel HTTP server:

For native development with artisan serve, use socket-bridge:dev --serve to start Laravel as well. See the installation guide for Docker, Sail, Herd, Valet and HTTPS setup.

Broadcast an event

Create app/Events/OrderUpdated.php:

Authorize access in routes/channels.php. This example assumes the user has an orders relationship:

Dispatch the event from your application:

ShouldBroadcast sends through Laravel's queue, which socket-bridge:dev runs for you. Use ShouldBroadcastNow for immediate dispatch.

Receive it with Socket.IO

Connect to your gateway and request connection tickets from your Laravel API. Replace the example URLs with your own.

The example uses authHeaders from your application's existing login flow. With the default Laravel session authentication, include the current CSRF token as X-CSRF-TOKEN; for bearer authentication, use an Authorization header and configure the matching Laravel guard.

Each connection needs a fresh authentication ticket; the auth callback requests one on every attempt. The connect handler rejoins the channel after reconnect. Reload current application data after an interruption, since missed events are not replayed.

For a separate frontend origin, allow it in Laravel's CORS configuration and socket-bridge.gateway.origins. Cookie authentication also requires credentialed CORS requests and cookies configured for your frontend domain.

For long-lived connections, handle bridge.session and session:refresh as described in authentication examples for Sanctum.

Send a command to Laravel

Generate a handler:

Implement your business logic in the generated handler and register it in a service provider:

See the handler example for validation and authorization. Once connected, send the command using Socket.IO:

The acknowledgement contains the Laravel handler's result after processing through Redis Streams. To safely retry an unknown outcome, supply a command ID before the callback: socket.emit('order.pay', payload, { id: commandId }, callback). Reuse that ID and payload for retries. See acknowledgements and timeouts.

Send with the facade

Target a user or an authorized channel directly:

To persist an event together with a database change, use the transactional outbox:

The business update and outbox must use the same database connection. The outbox worker publishes the event to Redis and retries after failures.

Typing and other short-lived signals can expire before delivery:

Register short-lived incoming commands with ttlSeconds: 5 as the third argument to CommandRegistry::register(). Durable business events continue to use the transactional outbox. See delivery controls.

More ways to use the bridge

Contributing

See SECURITY.md to report a vulnerability.

License

MIT.