blax-software/laravel-websockets

An easy to launch a Pusher-compatible WebSockets server for Laravel.

2.0.0-beta.37 2022-02-12 11:11 UTC

Requires

• cboden/ratchet: ^0.4.1
• clue/redis-react: ^2.5
• evenement/evenement: ^2.0|^3.0
• facade/ignition-contracts: ^1.0
• guzzlehttp/psr7: ^1.7|^2.0
• illuminate/broadcasting: ^6.3|^7.0|^8.0|^9.0
• illuminate/console: ^6.3|^7.0|^8.0|^9.0
• illuminate/http: ^6.3|^7.0|^8.0|^9.0
• illuminate/queue: ^6.3|^7.0|^8.0|^9.0
• illuminate/routing: ^6.3|^7.0|^8.0|^9.0
• illuminate/support: ^6.3|^7.0|^8.0|^9.0
• pusher/pusher-php-server: ^3.0|^4.0|^5.0|^6.0|^7.0
• react/promise: ^2.8
• symfony/http-kernel: ^4.4|^5.4|^6.0
• symfony/psr-http-message-bridge: ^1.1|^2.0

Requires (Dev)

• clue/block-react: ^1.4
• laravel/legacy-factories: ^1.1
• orchestra/testbench-browser-kit: ^4.0|^5.0|^6.0
• phpunit/phpunit: ^8.5.8|^9.3.3

Suggests

• ext-pcntl: Running the server needs pcntl to listen to command signals and soft-shutdown.
• doctrine/dbal: Required to run database migrations (^2.9|^3.0).

MIT

• Marcel Pociot
• Freek Van der Herten
• Alex Renoki

• php
• laravel
• beyondcode
• laravel-websockets

README

Note

This package is actively maintained as a fork of beyondcode/laravel-websockets.

Plug-and-play WebSockets for Laravel with a Pusher-compatible protocol, a fast fork-based handler, and practical helpers for broadcasting and testing.

Why this package

• Drop-in broadcasting backend for Laravel apps that already use Echo/Pusher-compatible clients
• Fast local handler with async processing via pcntl_fork
• Protocol compatibility for both modern websocket.* and legacy pusher:* action formats
• Built-in developer ergonomics: helper functions, service methods, and rich test helpers

Install in 2 minutes

1. Install package

composer require blax-software/laravel-websockets

1. Publish config

php artisan vendor:publish --provider="BlaxSoftware\\LaravelWebSockets\\WebSocketsServiceProvider" --tag="config"

1. Start server

php artisan websockets:serve

Default server URL is ws://127.0.0.1:6001.

Helper functions (broadcast from anywhere)

The package ships with global helpers in src/helpers_global.php.

// Broadcast to everyone on a channel
ws_broadcast('chat.message', ['text' => 'Hello'], 'chat');

// Whisper to specific socket IDs only
ws_whisper('chat.typing', ['typing' => true], ['1234.1', '1234.2'], 'chat');

// Broadcast to everyone except listed sockets
ws_broadcast_except('chat.message', ['text' => 'Server msg'], ['1234.1'], 'chat');

// Check if local unix-socket broadcaster is available
if (ws_available()) {
	ws_broadcast('app.health', ['ok' => true]);
}

// Build protocol auth payload for private/presence channels
$auth = wsSession('private-updates', ['user_id' => 7, 'user_info' => ['name' => 'Jane']]);

Service API

Use the service directly when you prefer explicit class calls over helpers.

use BlaxSoftware\LaravelWebSockets\Services\WebsocketService;

WebsocketService::send('metrics.tick', ['count' => 1], 'websocket');
WebsocketService::whisper('chat.typing', ['typing' => true], ['1234.1'], 'chat');
WebsocketService::broadcastExcept('chat.message', ['text' => 'Hi'], ['1234.1'], 'chat');

// Optional in-process tracking helpers
WebsocketService::setUserAuthed($socketId, $userId);
$authed = WebsocketService::getAuthedUsers();

Testing experience

The test suite includes helper-first patterns so WebSocket tests stay short and readable.

Test helpers

• newConnection()
• newActiveConnection(['channel'])
• newPrivateConnection('private-channel')
• newPresenceConnection('presence-channel', ['user_id' => 1, 'user_info' => [...]])

Example

$connection = $this->newActiveConnection(['chat']);

$this->wsHandler->onMessage($connection, new Message([
	'event' => 'websocket.ping',
	'data' => new stdClass(),
]));

$connection->assertSentEvent('websocket.pong');

Run tests:

vendor/bin/phpunit --exclude-group=stability,stress,integration,requires-server

Documentation

• Main docs: docs
• Getting started: docs/getting-started/introduction.md
• Helper & testing guide: docs/advanced-usage/helpers-and-testing.md

Changelog

See CHANGELOG.

Security

Please report vulnerabilities via issue tracker or by email: [e-mail].

Credits

• Marcel Pociot
• Freek Van der Herten
• All Contributors

License

MIT. See LICENSE.md.