README

Laravel WebSockets

Plug-and-play WebSockets for Laravel with a Pusher-compatible protocol, async fork-based handling, attribute-driven routing, and live operational tooling.

Note

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

Features

• #[Websocket] attribute on regular HTTP controllers — turn any controller method into a WebSocket-callable endpoint with one annotation, no second class to maintain

• Async processing — incoming messages are handled in pcntl_fork child processes, so a slow handler never blocks the event loop

• Broadcast from anywhere — ws_broadcast(), ws_whisper(), ws_broadcast_except() helpers and a static WebsocketService API let any controller, job, or service push events to any channel

• Multiple channel types — public, private-*, presence-*, and open-presence-* channels with the standard auth handshake

• Live ops tooling — php artisan websockets:watch renders connection counts, authenticated users, and per-channel connections, refreshing every second:

  WebSocket Server — Live Stats
  2026-05-05 14:33:35 — refreshing every 1s (Ctrl+C to exit)
  
    Live Stats .......................................................................................................................................
    Total connections ............................................................................................................................. 12
    Authenticated users ............................................................................................................................ 3
    Active channels ................................................................................................................................ 1
  
  +-----------+-------------+
  | Channel   | Connections |
  +-----------+-------------+
  | websocket | 12          |
  +-----------+-------------+
  

• Automatic route recognition — controller class and method names map to event names automatically (FlightschoolController::index → flightschool.index); override per method or per class via #[Websocket(event: ..., prefix: ..., suffix: ..., needAuth: true)]

• Hot code reload in dev, OPcache in prod — websocket:steer cache:clear clears OPcache and the controller resolver cache without restarting the running server, so iteration is instant in development while production runs with fully warmed caches

• Pusher-compatible protocol — supports both modern websocket.* and legacy pusher:* action formats, drop-in for Echo and pusher-js clients

• Test helpers — newConnection(), newActiveConnection(), newPrivateConnection(), newPresenceConnection(), plus assertSentEvent() keep WebSocket tests short

Requirements

• PHP 8.1+
• Laravel 9, 10, 11 or 12
• ext-pcntl (for async fork-based handling)

Installation

composer require blax-software/laravel-websockets

Publish the config:

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

Start the server:

php artisan websockets:serve

Default URL is ws://127.0.0.1:6001.

Quick Start

1. Mark a regular controller method as WebSocket-reachable

use BlaxSoftware\LaravelWebSockets\Attributes\Websocket;

class FlightschoolController extends Controller
{
    #[Websocket]                      // event: "flightschool.index"
    public function index() { ... }

    #[Websocket(event: 'flightschools.list')]   // explicit override
    public function list() { ... }

    #[Websocket(needAuth: true)]      // requires authenticated socket
    public function update() { ... }
}

2. Broadcast from anywhere

// Helpers
ws_broadcast('chat.message', ['text' => 'Hello'], 'chat');
ws_whisper('chat.typing', ['typing' => true], ['1234.1', '1234.2'], 'chat');
ws_broadcast_except('chat.message', ['text' => 'Server msg'], ['1234.1'], 'chat');

// Service API
use BlaxSoftware\LaravelWebSockets\Services\WebsocketService;

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

3. Build a private/presence auth payload

$auth = wsSession('private-updates', [
    'user_id'   => 7,
    'user_info' => ['name' => 'Jane'],
]);

4. Watch live stats

php artisan websockets:watch          # connection counts and channels
php artisan websockets:watch -v       # expanded per-connection rows
php artisan websockets:info           # one-shot snapshot

5. Iterate without restarting

php artisan websocket:steer cache:clear   # clear OPcache + resolver cache
php artisan websockets:restart            # graceful restart
php artisan websocket:restart-hard        # signal-based force restart

Channel Types

Testing

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

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

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

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
• Custom handlers: docs/advanced-usage/custom-websocket-handlers.md

Changelog

See CHANGELOG.

Security

Please report vulnerabilities via the issue tracker or by email: office@blax.at.

Credits

• Marcel Pociot
• Freek Van der Herten
• All Contributors

License

MIT. See LICENSE.md.

Star History