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

Laravel Socket.IO Bridge

Reusable Laravel integration for authenticated Socket.IO events transported through Redis.

The package contains the Laravel integration layer. The companion Socket.IO gateway is included in the node/ directory and runs as a separate Node.js service.

Quick start

Run these steps in order:

Then:

1. Add the Redis settings shown below to .env.
2. Register testEvent in AppServiceProvider.
3. Start Redis and Laravel.
4. Start the gateway with php artisan socket-bridge:install --start.
5. Connect a Socket.IO client with a valid access token.

socket-bridge:install only checks Node.js/npm and installs dependencies. The --start option runs the gateway in the current terminal. For production, use Supervisor so it starts and restarts automatically.

Requirements

• PHP 8.2 or newer
• Laravel 10 or newer
• Redis 6 or newer
• Node.js 20 or newer for the Socket.IO gateway

Installation

Install the package with Composer:

Publish the package configuration:

The package service provider is registered automatically through Laravel package discovery.

After installation, use the package command to verify Node.js and npm and install the gateway dependencies:

If Node.js or npm is not installed, the command stops and asks you to install Node.js 20 or newer before running it again. To install the dependencies and run the gateway in the foreground:

For production, run the install command without --start, then use the Supervisor configuration below so the gateway is monitored and restarted automatically.

Available Artisan commands

There is currently no php artisan socket-bridge:test command. Testing is done by registering the testEvent example below, starting Redis, Laravel, and the gateway, and then emitting testEvent from a Socket.IO client.

Updating the package

For an existing Laravel application, update the package with Composer:

After updating, run the installer again so the gateway dependencies match the package version:

If the published configuration file has changed, republish it after reviewing your local settings:

Restart the gateway after an update. If Supervisor manages it:

Commit composer.lock in the Laravel application when using a locked deployment workflow.

Configuration

The published configuration file is:

Redis settings can be configured through environment variables:

If SOCKET_BRIDGE_REDIS_URL is not set, the package falls back to REDIS_URL and then to the default Redis URL defined in the configuration file.

Registering an event

The package automatically discovers listener classes in app/Listeners whose names start with HandleSocket.

For example, create app/Listeners/HandleSocketTestEvent.php:

The prefix is removed and the first remaining character is converted to lowercase:

Listeners are resolved through Laravel's service container, so constructor dependencies are supported. The handle() method receives the payload and authenticated user ID.

Manual registration is also supported through SocketEventRegistry:

The application remains responsible for authorization, payload validation, and business logic.

Test event

The quickest test is to create app/Listeners/HandleSocketTestEvent.php using the example above. After Laravel starts, the listener is discovered automatically. Emit testEvent from the Socket.IO client shown below.

Manual registration remains available when you need a custom event name or closure:

From a Socket.IO client, emit the event after connecting with a valid access token:

The handler receives the event payload and authenticated user ID. Return an array to send a response to the client. Add authorization and payload validation inside the handler or in your application's existing authorization layer.

You do not need php artisan make:event or php artisan make:listener; those commands create Laravel event/listener classes and are not used for socket listener discovery.

Automatic discovery runs when Laravel boots. Restart Laravel and the gateway after adding a new listener while the application is running.

Test the event

Run the following in separate terminals:

Then connect a Socket.IO client with a valid access token and emit testEvent. A successful test returns the message, user_id, and payload from the PHP handler. If the test fails, check the access token, Redis URL, matching channel names, gateway port, and CORS origin.

Server setup

The bridge requires Redis, the Laravel application, and the Node.js Socket.IO gateway:

1. Start Redis.
2. Install and configure the Laravel package.
3. Start the Socket.IO gateway from the package's node/ directory.

Example local setup:

The gateway listens on port 6006 by default. Configure the connection with:

The Laravel and gateway Redis channel settings must match. If you change the Laravel SOCKET_BRIDGE_*_CHANNEL values, set the corresponding variables for the Node.js gateway too.

Run the gateway automatically

For production, use a process manager so the gateway starts on boot and restarts if it exits. For example, install Supervisor and create /etc/supervisor/conf.d/socket-bridge-gateway.conf:

Replace /var/www/your-app, www-data, the Redis URL, and the allowed origin with your deployment values. Then enable the service:

Useful management commands:

Do not start the gateway from a Laravel service provider or an HTTP request. It is a long-running service and should be monitored independently from PHP.

Troubleshooting

• ECONNREFUSED: confirm that Redis is running and that REDIS_URL points to the correct host and port.
• Laravel Redis listener timed out: confirm that Laravel is running and listening on the same Redis request channel as the gateway.
• CORS errors: set SOCKET_IO_CORS_ORIGIN to the exact origin of the web client.
• Event responses are missing: verify that the event name passed to listen() exactly matches the name emitted by the client and that all Redis channel names match.
• Gateway stops after logout or reboot: use Supervisor or another process manager and inspect its log files.

License

This package is released under the MIT license.