Laravel Wave

https://github.com/qruto/laravel-wave
Admin
Laravel Wave enables real-time server broadcasting over native HTTP using Server-Sent Events,...
Tokens:63,990
Snippets:430
Trust Score:6.6
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install Wave for Laravel 11 or higher

Source: https://github.com/qruto/laravel-wave/blob/main/README.md

Install the package via Composer and set up broadcasting with the artisan command.

```bash
composer require qruto/laravel-wave
php artisan install:broadcasting
```

--------------------------------

### Install Wave for Laravel 10 or lower

Source: https://github.com/qruto/laravel-wave/blob/main/README.md

Install Wave on both server and client sides using Composer and npm.

```bash
composer require qruto/laravel-wave
npm install laravel-wave
```

--------------------------------

### Install broadcasting command usage

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/console-commands.md

Run `php artisan install:broadcasting` to start the interactive installation for broadcasting and Wave. The command prompts for Redis driver, Node dependencies, and config publishing, then copies stubs and runs package-manager-specific build commands.

```bash
php artisan install:broadcasting
```

--------------------------------

### Typical production setup for config/wave.php

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/configuration.md

Example configuration for Laravel Wave in a production environment. Sets resume lifetime to 60 seconds, retry delay to 2000 ms, enables pings with a 30-second frequency, and uses the 'web' guard and middleware.

```php
// config/wave.php (published)
return [
    'resume_lifetime' => 60,          // history kept 60s -> reconnect resume window
    'retry' => 2000,                  // client waits 2s before reconnecting
    'ping' => [
        'enable' => true,
        'frequency' => 30,            // ping at most every 30s of idle
        'eager_env' => null,          // no env gets eager pings in production
    ],
    'path' => 'wave',
    'middleware' => ['web'],
    'auth_middleware' => 'auth',
    'guard' => 'web',
];
```

```bash
# .env
BROADCAST_CONNECTION=redis
# optional: serve with more workers
PHP_CLI_SERVER_WORKERS=10
```

--------------------------------

### Usage example: listening to SseConnectionClosedEvent

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/events.md

Shows how to observe disconnects by registering an event listener that logs the connection ID and user identifier.

```php
use Qruto\Wave\Events\SseConnectionClosedEvent;
use Illuminate\Support\Facades\Event;

// observe disconnects in your app:
Event::listen(SseConnectionClosedEvent::class, function (SseConnectionClosedEvent $e) {
    logger()->info("connection {$e->connectionId} closed", ['user' => $e->user?->getAuthIdentifier()]);
});
```

--------------------------------

### Basic usage example

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/sse-server-sent-event.md

Creates a ServerSentEvent with named arguments and echoes it. Output shows the SSE frame with event, data, and id fields.

```php
use Qruto\Wave\Sse\ServerSentEvent;

$frame = new ServerSentEvent(
    event: 'community.OrderShipped',
    data: json_encode(['id' => 42]),
    id: '1717000000000-0',
);

echo $frame;
// event: community.OrderShipped
// data: {"id":42}
// id: 1717000000000-0
//
```

--------------------------------

### Usage example for SsePingEvent

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/events.md

Shows how to broadcast a keep-alive ping to every connection using the SsePingEvent. Clients receive an SSE event named 'general.ping' with data typically '[]' or null.

```php
use Qruto\Wave\Events\SsePingEvent;

// keep-alive: broadcast a ping to every connection
event(new SsePingEvent());

// clients receive: event: general.ping  data: <whatever Redis publishes, typically "[]" or null>

```

--------------------------------

### Usage example for WaveConnection route

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/http-wave-connection.md

Shows how to register the WaveConnection controller as a route, equivalent to the shipped route. Includes a client-side comment using EventSource to listen for the 'general.connected' event.

```php
use Qruto\Wave\Http\Controllers\WaveConnection;
use Illuminate\Support\Facades\Route;

// Equivalent to the route shipped in routes/routes.php:
Route::get('/wave', WaveConnection::class)->name('wave.connection');

// Client side (npm laravel-wave-client, e.g. Echo's WaveConnector):
//   const es = new EventSource('/wave');
//   es.addEventListener('general.connected', e => console.log(e.data)); // socket id
```

--------------------------------

### Usage example — from a broadcast payload

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/sse-event-factory.md

Shows how to use EventFactory::fromBroadcastEvent() to create events for multiple channels from a payload. The example demonstrates that the data property references the same array instance as the input payload.

```php
use Qruto\Wave\Sse\EventFactory;

$payload = ['order' => 42, 'socket' => '123.456'];

$events = EventFactory::fromBroadcastEvent(
    ['community', 'user.1'],
    'OrderShipped',
    $payload,
);

count($events);           // 2
$events[0]->channel;      // 'community'
$events[0]->socket;       // '123.456'
$events[0]->data;         // same array instance as $payload
```

--------------------------------

### Usage example of laravel11OrHigher() helper

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/broadcasting-user-identifier.md

Shows how to conditionally execute Laravel 11+ only behavior using the helper function.

```php
use Qruto\Wave\WaveServiceProvider;

// anywhere in your app:
if (laravel11OrHigher()) {
    // Laravel 11+ only behavior (install:broadcasting etc.)
}
```

--------------------------------

### Configure Wave or Echo client options

Source: https://github.com/qruto/laravel-wave/blob/main/README.md

Pass client options to the Wave or Echo instance. The options include endpoint, namespace, auth headers, authentication endpoint, CSRF token, bearer token, request settings, pauseInactive, and debug. The example shows two ways to instantiate: using Echo with WaveConnector and using Wave directly with custom authEndpoint and csrfToken.

```javascript
new Echo({
    broadcaster: WaveConnector,
    endpoint: '/sse-endpoint',
    bearerToken: 'bearer-token',
    //...
});

// or

new Wave({
    authEndpoint: '/custom-broadcasting/auth',
    csrfToken: 'csrf-token',
})
```

--------------------------------

### sse:ping usage examples

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/console-commands.md

Shows how to run the sse:ping command: a single ping without options, or a blocking loop with --interval=30 to ping every 30 seconds.

```bash
php artisan sse:ping                 # single ping
php artisan sse:ping --interval=30   # ping every 30s (blocking loop)
```

--------------------------------

### Usage: php artisan serve

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/console-commands.md

Runs the serve command; when Wave is installed, it triggers an interactive prompt the first time to configure the worker count.

```bash
php artisan serve
# runs an interactive prompt the first time when Wave is installed
```

--------------------------------

### Usage example for PresenceChannelJoinEvent

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/events.md

Broadcasts the event with a user key, user info, and channel name. The channel is passed without the 'presence-' prefix. Subscribers receive the event 'presence-lobby.join' with the user info as data.

```php
use Qruto\Wave\Events\PresenceChannelJoinEvent;

broadcast(new PresenceChannelJoinEvent('1', ['id' => 1, 'name' => 'Ada'], 'lobby'))->toOthers();
// -> PresenceChannel('lobby'), as: 'join'
// subscribers receive: event: presence-lobby.join  data: {"id":1,"name":"Ada"}
```

--------------------------------

### Manual ping debugging example

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/http-ping-connections-middleware.md

Shows how to manually instantiate the middleware for testing decision branches. The commented config lines demonstrate forcing eager_env to null and frequency to 30 so a request pings only when no event was recorded within 30 seconds.

```php
// Debug: force the decision branches in a controller for testing
$middleware = app(\Qruto\Wave\Http\Middleware\PingConnections::class);

// config(['wave.ping.eager_env' => null, 'wave.ping.frequency' => 30]);
// A request now pings only when no event was recorded within 30s.
```

--------------------------------

### GET /{wave.path}/

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/endpoints.md

Establishes a Server-Sent Events (SSE) connection for real-time event streaming. The client receives a stream of events, with the first frame being 'general.connected' to provide the socket ID.

```APIDOC
## GET /{wave.path}/

### Description
Establishes a Server-Sent Events (SSE) connection for real-time event streaming. The client receives a stream of events, with the first frame being 'general.connected' to provide the socket ID.

### Method
GET

### Endpoint
/{wave.path}/

### Parameters
#### Headers
- **Last-Event-Id** (string) - Optional - Redis stream id (`{millis}-{seq}`) to resume and replay missed events from history.
- **X-Socket-Id** (string) - Optional - Previous socket id to exclude the client's own replayed events.
- **Accept** (string) - Optional - Any value; response is `text/event-stream`.
- **Cookie session / CSRF** - Optional - Needed only if protected channels require the session.

### Response
#### Success Response (200)
Streaming response with headers:
- **Content-Type**: `text/event-stream`
- **Connection**: `keep-alive`
- **Cache-Control**: `no-cache, no-store, must-revalidate, pre-check=0, post-check=0`
- **X-Accel-Buffering**: `no`
- **X-Socket-Id**: `<new socket id>` (pattern `{int}.{int}`)

Stream body consists of SSE frames with fields:
- **event**: `{channel}.{name}` (e.g., `general.connected`, `community.OrderShipped`)
- **data**: string (JSON for object payloads, raw for scalar/system events)
- **id**: `{millis}-{seq}` (Redis stream id, present on persisted events)
- **retry**: integer (present only when `config('wave.retry')` is non-null)

First frame is always `general.connected` with `data` as the new socket id and `id` as the stream id.

#### Response Example
```
event: general.connected
data: 12345.67890
id: 1717000000000-0

event: community.OrderShipped
data: {"id":42,"status":"shipped"}
id: 1717000000001-0

event: presence-lobby.join
data: {"id":1,"name":"Ada"}
id: 1717000000002-0

event: private-chat.client-typing
data: {"user_id":1,"typing":true}
id: 1717000000003-0
```
```

--------------------------------

### Example SSE frame output

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/sse-server-sent-event.md

Shows the output of __toString() for a frame with event, data, and id fields. The trailing blank line terminates the SSE block.

```text
event: community.OrderShipped
data: {"id":42,"status":"shipped"}
id: 1717000000000-0


```

--------------------------------

### Verifying behavior with a real client

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/sse-server-sent-event-stream.md

Illustrative example of client reconnect flow as implemented by the JS laravel-wave package. Shows the expected HTTP responses and headers for initial connection and reconnection with Last-Event-Id.

```php
use Illuminate\Support\Facades\Http; // illustrative: real SSE consumption needs a stream reader

// Client reconnect flow (as implemented by the JS laravel-wave package):
// 1. open  GET /wave                      -> 200 text/event-stream, X-Socket-Id: <A>
//    server sends:  id: <streamId>\nevent: general.connected\ndata: <A>\n
// 2. on drop, reopen GET /wave
//    headers: Last-Event-Id: <streamId>   -> replays missed events (except general.*)
//    X-Socket-Id is regenerated server-side; old-socket events are not replayed.
```

--------------------------------

### Usage example of BroadcastingUserIdentifier trait

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/broadcasting-user-identifier.md

Shows how to use the trait in a custom class to obtain the user's broadcasting key via the userKey() method.

```php
use Qruto\Wave\BroadcastingUserIdentifier;
use App\Models\User;

class MyPresenceReporter
{
    use BroadcastingUserIdentifier;

    public function report(User $user): string
    {
        return $this->userKey($user);
    }
}
```

--------------------------------

### echo.js stub for WaveConnector

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/console-commands.md

Stub file `stubs/echo.js` (copied to `resources/js/echo.js` by the install command) that sets up Laravel Echo with the WaveConnector broadcaster. Used when the broadcasting routes file is missing or when the user confirms installation.

```javascript
import Echo from 'laravel-echo';

import { WaveConnector } from 'laravel-wave';

window.Echo = new Echo({
    broadcaster: WaveConnector,
});
```

--------------------------------

### Start the event subscriber

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/sse-server-sent-event-stream.md

Starts the long-running message pump, passing a callback that handles each incoming Redis message by converting it to an event and invoking the event handler. This blocks until the connection ends.

```php
$this->eventSubscriber->start(function (string $message, string $channel) use ($request, $newSocket) {
    $this->eventHandler($request, $newSocket)(EventFactory::fromRedisMessage($message, $channel));
}, $request, $newSocket);
```

--------------------------------

### GET /wave/presence-channel-users

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/endpoints.md

Lists the users currently present in a given presence channel. Requires authentication and returns an array of userInfo objects.

```APIDOC
## [GET] /wave/presence-channel-users

### Description
Lists the users currently present in a given presence channel. Requires authentication and returns an array of userInfo objects.

### Method
GET

### Endpoint
/wave/presence-channel-users

### Parameters
#### Query Parameters
- **channel_name** (string) - Required - Full presence channel name, e.g. `presence-lobby` (also used for `Broadcast::auth`; if a `socket_id` is supplied, it's copied to the `X-Socket-Id` header)

### Response
#### Success Response (200)
Array of `userInfo` objects for users currently in the channel.

#### Response Example
```json
[
  {"id": 1, "name": "Ada"},
  {"id": 2, "name": "Grace"}
]
```

`userInfo` shape is whatever the channel authorization callback returned in `channel_data.user_info`.
```

--------------------------------

### GET /wave/presence-channel-users - 200 OK response

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/endpoints.md

Response body for listing users in a presence channel. Returns an array of userInfo objects for users currently in the channel.

```json
[
  {"id": 1, "name": "Ada"},
  {"id": 2, "name": "Grace"}
]
```

--------------------------------

### GET {wave.path}/

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/http-wave-connection.md

Establishes a Server-Sent Events (SSE) connection for real-time events. Returns a streaming response with Content-Type text/event-stream and sends an initial 'general.connected' event with the new socket ID.

```APIDOC
## [GET] {wave.path}/

### Description
Establishes an SSE stream connection. The response is a streaming HTTP response that stays open, sending events as they occur. The first event is always `general.connected` with the new socket ID as data.

### Method
GET

### Endpoint
`{wave.path}/` (route name: `wave.connection`)

### Parameters
#### Path Parameters
- `wave.path` (string) - Required - The base path for the Wave connection (configured in the package).

#### Request Headers
- `Last-Event-Id` (string) - Optional - Stream ID to resume from; missed events are replayed.
- `X-Socket-Id` (string) - Optional - Previous socket ID; used for `toOthers` filtering of replayed events.

### Response
#### Success Response (200)
- `Content-Type: text/event-stream`
- `Connection: keep-alive`
- `Cache-Control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0`
- `X-Accel-Buffering: no`
- `X-Socket-Id: <new socket id>`

#### Response Example
```
HTTP/1.1 200 OK
Content-Type: text/event-stream
Connection: keep-alive
Cache-Control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0
X-Accel-Buffering: no
X-Socket-Id: abc123

event: general.connected
data: abc123
```

### Notes
- No authentication is enforced at the route level; per-channel authorization is handled inside the stream (unauthorized access to private/presence channels is silently dropped).
- The response blocks for the connection lifetime; PHP timeouts are disabled.
- The controller is registered under the `wave.middleware` group (default `['web']`).
```

--------------------------------

### Typical route-served usage of WaveConnection

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/sse-server-sent-event-stream.md

No direct usage needed: GET /wave hits WaveConnection::__invoke, which returns $responseFactory->toResponse($request). See routes/routes.php and http-wave-connection.md.

```php
// No direct usage needed: GET /wave hits WaveConnection::__invoke,
// which returns $responseFactory->toResponse($request).
// See routes/routes.php and http-wave-connection.md.
```

--------------------------------

### Usage example — converting a Redis message

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/sse-event-factory.md

Shows how to use EventFactory::fromRedisMessage() to convert a Redis message into an event object. The example demonstrates accessing channel, name, data, id, and socket properties.

```php
use Qruto\Wave\Sse\EventFactory;

$event = EventFactory::fromRedisMessage(
    '{"event":"OrderShipped","data":{"id":42,"broadcast_event_id":"1717000000000-0","socket":"100.200"}}',
    'community'
);

$event->channel;   // 'community'
$event->name;      // 'OrderShipped'
$event->data;      // ['id' => 42]
$event->id;        // '1717000000000-0'
$event->socket;    // '100.200'
```

--------------------------------

### Fluent mutators and manual flush example

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/sse-server-sent-event.md

Uses fluent setters to modify id, retry, and data, then calls echo() to output and flush. The retry value is 30000 ms (30 seconds).

```php
use Qruto\Wave\Sse\ServerSentEvent;

$frame = (new ServerSentEvent('status.tick', '{}'))
    ->setId('1717000000001-0')
    ->setRetry(30_000)          // client reconnects after 30s on drop
    ->setData('{"alive":true}');

$frame->echo();                 // echoes and flushes via __invoke()
```

--------------------------------

### GET /{wave.path}/presence-channel-users

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/endpoints.md

Retrieves the list of users currently present in presence channels. This endpoint is protected by authentication middleware.

```APIDOC
## GET /{wave.path}/presence-channel-users

### Description
Retrieves the list of users currently present in presence channels. This endpoint is protected by authentication middleware.

### Method
GET

### Endpoint
/{wave.path}/presence-channel-users

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token or session cookie for authentication.

### Response
#### Success Response (200)
Returns a list of users currently present in presence channels.

#### Response Example
```json
[
  {"id": 1, "name": "Ada"},
  {"id": 2, "name": "Bob"}
]
```
```

--------------------------------

### Usage example — in a custom history consumer / filter

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/storage-broadcasting-event.md

Shows filtering events from history and sending them. Also demonstrates direct field access to public properties for toOthers checks.

```php
use Qruto\Wave\Storage\BroadcastingEvent;

/** @var \Illuminate\Support\Collection<int, BroadcastingEvent> $events */
$events = $history->getEventsFrom('1717000000000-0');

$events
    ->filter(fn (BroadcastingEvent $event) => $event->channel !== 'general')
    ->each(fn (BroadcastingEvent $event) => $event->send());

// Field access is direct (public):
$event->data['userId'];
$event->socket === $lastSocket;   // toOthers check
```

--------------------------------

### Usage example for PresenceChannelLeaveEvent

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/events.md

Broadcasts a leave event with userId '1', userInfo array, and channel 'lobby' using toOthers(). The event is sent on PresenceChannel('lobby') as 'leave'. After ServerSentEventStream reshaping, other subscribers receive the SSE event 'presence-lobby.leave' with data containing only the userInfo.

```php
use Qruto\Wave\Events\PresenceChannelLeaveEvent;

broadcast(new PresenceChannelLeaveEvent('1', ['id' => 1, 'name' => 'Ada'], 'lobby'))->toOthers();
// -> PresenceChannel('lobby'), as: 'leave'
// other subscribers receive (after ServerSentEventStream reshaping):
// event: presence-lobby.leave  data: {"id":1,"name":"Ada"}
```

--------------------------------

### Usage example — resume flow

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/storage-broadcast-event-history.md

Shows how the framework uses the history storage: resolving the RedisStream binding, fetching missed events after a client reconnect with `Last-Event-Id`, and recording a broadcast via `pushEvent`. The caller filters out channel === 'general' before sending.

```php
use Qruto\Wave\Storage\BroadcastEventHistory;
use Qruto\Wave\Storage\BroadcastEventHistoryRedisStream;

$history = app(BroadcastEventHistory::class);      // resolves RedisStream binding

// client reconnects with `Last-Event-Id: 1717000000000-3`:
$missed = $history->getEventsFrom('1717000000000-3');
// Collection<BroadcastingEvent> — every entry at/after 1717000000000-4
// (the caller filters out channel === 'general' before sending)

// a broadcast is being recorded (inside the wrapped Redis broadcaster):
$id = $history->pushEvent($event);                 // e.g. '1717000000123-0'
```

--------------------------------

### Usage example: RedisSubscriber standalone

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/server-sent-event-subscriber.md

Shows how to use RedisSubscriber directly in an application, typically invoked by ServerSentEventStream but usable standalone. The callback receives the raw Redis message body and channel/pattern for every message on every Redis channel.

```php
use Qruto\Wave\RedisSubscriber;

// Typicallly invoked by ServerSentEventStream — but usable standalone:
$subscriber = app(RedisSubscriber::class);

$subscriber->start(
    function (string $message, string $channel) {
        // called for every message on every Redis channel
        logger()->info("$channel: $message");
    },
    request(),
    '123.456'
);
```

--------------------------------

### ClientEvent usage example

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/events.md

Dispatches a ClientEvent with 'typing' name on private channel 'conversation.42' with user_id data, using ->toOthers() to exclude the sender. Subscribers receive SSE event 'private-conversation.42.client-typing' with data {"user_id":1}.

```php
use Qruto\Wave\Events\ClientEvent;

broadcast(new ClientEvent('typing', 'private-conversation.42', ['user_id' => 1]))->toOthers();
// server methods: broadcastOn() -> PrivateChannel('conversation.42')
//                 broadcastAs() -> 'client-typing'
// subscribers receive: event: private-conversation.42.client-typing
//                      data: {"user_id":1}
```

--------------------------------

### index() - Get presence channel users

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/http-presence-channel-users-controller.md

Returns a JSON array of userInfo objects for the given presence channel. Requires authentication and the channel_name query parameter, which the middleware needs for Broadcast::auth. Responds with HTTP 200.

```php
public function index()
{
    return response()->json($this->repository->getUsers(request()->channel_name));
}
```

--------------------------------

### Usage example — sending a frame manually

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/storage-broadcasting-event.md

Creates a BroadcastingEvent and calls send() to output an SSE frame. The comment shows the echoed output: event, data, id, and retry (only if config('wave.retry') is set).

```php
use Qruto\Wave\Storage\BroadcastingEvent;

$event = new BroadcastingEvent(
    channel: 'community',
    name: 'OrderShipped',
    data: ['id' => 42, 'status' => 'shipped'],
    id: '1717000000000-0',
    socket: null,
);

$event->send();
// echoes:
// event: community.OrderShipped
// data: {"id":42,"status":"shipped"}
// id: 1717000000000-0
// retry: 2000   (only if config('wave.retry') is set)
//
```

--------------------------------

### ClientEvent class implementation

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/events.md

Broadcastable event for client-to-client whispers. Constructor takes name, channel (must start with 'private-' or 'presence-'), and data. broadcastOn() maps presence-* to PresenceChannel and private-* to PrivateChannel; broadcastWith() wraps scalar data in an array; broadcastAs() returns 'client-{name}'. Channel validation is not performed here—it happens in SendWhisper.

```php
class ClientEvent implements ShouldBroadcast
{
    use Dispatchable;
    use InteractsWithSockets;
    use SerializesModels;

    /**
     * Create a new event instance.
     *
     * @return void
     */
    public function __construct(protected string $name, protected string $channel, public $data) {}

    /**
     * Get the channels the event should broadcast on.
     *
     * @return \Illuminate\Broadcasting\Channel|array
     */
    public function broadcastOn()
    {
        $channelName = str($this->channel);

        return $channelName->startsWith('presence-')
                ? new PresenceChannel($channelName->after('presence-'))
                : new PrivateChannel($channelName->after('private-'));
    }

    public function broadcastWith()
    {
        return is_scalar($this->data) ? [$this->data] : $this->data;
    }

    public function broadcastAs(): string
    {
        return 'client-'.$this->name;
    }
}
```

--------------------------------

### Usage example: POST /wave/whisper with Http facade

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/http-send-whisper.md

Shows how to call the whisper endpoint using Laravel's Http facade. Requires X-Socket-Id and X-CSRF-TOKEN headers. The response status is 204. Other subscribers of the private channel receive an SSE event named private-conversation.42.client-typing with the data payload.

```php
use Illuminate\Support\Facades\Http;

$res = Http::withHeaders([
    'X-Socket-Id' => '111.111',
    'X-CSRF-TOKEN' => csrf_token(),
])->post('/wave/whisper', [
    'channel_name' => 'private-conversation.42',
    'event_name'   => 'typing',
    'data'         => ['user_id' => 1, 'typing' => true],
]);

$res->status(); // 204

// Other subscribers of private-conversation.42 receive SSE:
// event: private-conversation.42.client-typing
// data: {"user_id":1,"typing":true}

```

--------------------------------

### Send ping event every 30 seconds with sse:ping --interval

Source: https://github.com/qruto/laravel-wave/blob/main/README.md

Use this command to manually send a ping event at a specified interval to keep the SSE connection alive. The example sends a ping every 30 seconds, which is less than the default fastcgi_read_timeout of 60s, ensuring the connection remains persistent. Requires disabling automatic ping by setting ping.enable to false.

```bash
php artisan sse:ping --interval=30
```

--------------------------------

### Use Live Eloquent Models with Wave

Source: https://github.com/qruto/laravel-wave/blob/main/README.md

Create a Wave instance and listen to model events and notifications.

```javascript
import { Wave } from 'laravel-wave';

window.Wave = new Wave();

wave.model('User', '1')
    .notification('team.invite', (notification) => {
        console.log(notification);
    })
    .updated((user) => console.log('user updated', user))
    .deleted((user) => console.log('user deleted', user))
    .trashed((user) => console.log('user trashed', user))
    .restored((user) => console.log('user restored', user))
    .updated('Team', (team) => console.log('team updated', team));
```

--------------------------------

### Full config/wave.php configuration file

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/configuration.md

Published via `php artisan vendor:publish --tag="wave-config"`. Read via `config('wave.<key>')`. Contains all server-side options: `resume_lifetime` (requires Redis), `retry`, `ping` settings, `path`, `middleware`, `auth_middleware`, and `guard`. Comments are elided in this verbatim copy.

```php
return [

    'resume_lifetime' => 60,

    'retry' => null,

    'ping' => [
        'enable' => true,
        'frequency' => 30,
        'eager_env' => 'local', // null or array
    ],

    'path' => 'wave',

    'middleware' => [
        'web',
    ],

    'auth_middleware' => 'auth',

    'guard' => 'web',

];
```

--------------------------------

### GET /wave/presence-channel-users

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/http-presence-channel-users-controller.md

List all users currently present in a given presence channel.

```APIDOC
## [GET] /wave/presence-channel-users

### Description
List all users currently present in a given presence channel.

### Method
GET

### Endpoint
/wave/presence-channel-users

### Parameters
#### Query Parameters
- **channel_name** (string) - Required - The name of the presence channel to query.

### Request Example
```
GET /wave/presence-channel-users?channel_name=presence-lobby
```

### Response
#### Success Response (200)
- **users** (array) - List of users in the channel.

#### Response Example
```json
[
  {"id": 1, "name": "Ada"},
  {"id": 2, "name": "Grace"}
]
```
```

--------------------------------

### Publish Wave configuration

Source: https://github.com/qruto/laravel-wave/blob/main/README.md

Run this artisan command to publish the Wave configuration file to your application's config directory.

```bash
php artisan vendor:publish --tag="wave-config"
```

--------------------------------

### GET /wave/presence-channel-users

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/http-presence-channel-users-controller.md

Retrieves the list of users currently present in a presence channel. Requires authentication and the channel_name query parameter.

```APIDOC
## [GET] /wave/presence-channel-users

### Description
Retrieves the list of users currently present in a presence channel. Requires authentication and the channel_name query parameter.

### Method
GET

### Endpoint
/wave/presence-channel-users

### Parameters
#### Query Parameters
- **channel_name** (string) - Required - The presence channel name (e.g., `presence-{channel}`).

### Response
#### Success Response (200)
- **array** - JSON array of `userInfo` objects, one per present user.

#### Response Example
```json
[{"id":1,"name":"Ada"}, ...]
```
```

--------------------------------

### Publishing configuration with vendor:publish

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/wave-service-provider.md

Publishes config/wave.php using the wave-config tag.

```bash
php artisan vendor:publish --tag="wave-config"
# publishes config/wave.php
```

--------------------------------

### Manual invocation of RemoveStoredConnectionListener

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/listeners.md

Shows how to manually trigger the listener with an SseConnectionClosedEvent. The listener is auto-wired, but this example demonstrates direct usage with a user and connection ID.

```php
use Qruto\Wave\Events\SseConnectionClosedEvent;
use Qruto\Wave\Listeners\RemoveStoredConnectionListener;

// The listener is auto-wired; manual invocation:
$listener = app(RemoveStoredConnectionListener::class);

$listener->handle(new SseConnectionClosedEvent(auth()->user(), '111.111'));
// -> removes socket 111.111 from all presence channels of the user
// -> broadcasts presence-*.leave toOthers for fully-exited channels
```

--------------------------------

### Wave configuration file contents

Source: https://github.com/qruto/laravel-wave/blob/main/README.md

The published configuration file defines server options for Wave: resume lifetime, reconnection time, ping settings, routes path, middleware, and authentication guard. Adjust these values to control SSE connection behavior and route registration.

```php
return [

    /*
    |--------------------------------------------------------------------------
    | Resume Lifetime
    |--------------------------------------------------------------------------
    |
    | Define how long (in seconds) you wish an event stream to persist so it
    | can be resumed after a reconnect. The connection automatically
    | re-establishes with every closed response.
    |
    | * Requires a cache driver to be configured.
    |
    */
    'resume_lifetime' => 60,

    /*
    |--------------------------------------------------------------------------
    | Reconnection Time
    |--------------------------------------------------------------------------
    |
    | This value determines how long (in milliseconds) to wait before
    | attempting a reconnect to the server after a connection has been lost.
    | By default, the client attempts to reconnect immediately. For more
    | information, please refer to the Mozilla developer's guide on event
    | stream format.
    | https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format
    |
    */
    'retry' => null,

    /*
    |--------------------------------------------------------------------------
    | Ping
    |--------------------------------------------------------------------------
    |
    | A ping event is automatically sent on every SSE connection request if the
    | last event occurred before the set `frequency` value (in seconds). This
    | ensures the connection remains persistent.
    |
    | By setting the `eager_env` option, a ping event will be sent with each
    | request. This is useful for development or for applications that do not
    | frequently expect events. The `eager_env` option can be set as an `array` or `null`.
    |
    | For manual control of the ping event with the `sse:ping` command, you can
    | disable this option.
    |
    */
    'ping' => [
        'enable' => true,
        'frequency' => 30,
        'eager_env' => 'local', // null or array
    ],

    /*
    |--------------------------------------------------------------------------
    | Routes Path
    |--------------------------------------------------------------------------
    |
    | This path is used to register the necessary routes for establishing the
    | Wave connection, storing presence channel users, and handling simple whisper events.
    |
    */
    'path' => 'wave',

    /*
     |--------------------------------------------------------------------------
     | Route Middleware
     |--------------------------------------------------------------------------
     |
     | Define which middleware Wave should assign to the routes that it registers.
     | You may modify these middleware as needed. However, the default value is
     | typically sufficient.
     |
     */
    'middleware' => [
        'web',
    ],

    /*
     |--------------------------------------------------------------------------
     | Auth & Guard
     |--------------------------------------------------------------------------
     |
     | Define the default authentication middleware and guard type for
     | authenticating users for presence channels and whisper events.
     |
     */
    'auth_middleware' => 'auth',

    'guard' => 'web',

];
```

--------------------------------

### WaveServiceProvider class declaration

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/wave-service-provider.md

The provider class extends PackageServiceProvider and defines three methods: configurePackage, registeringPackage, and bootingPackage.

```php
class WaveServiceProvider extends PackageServiceProvider
{
    public function configurePackage(Package $package): void
    public function registeringPackage()
    public function bootingPackage()
}
```

--------------------------------

### Update Echo configuration for Laravel 10 or lower

Source: https://github.com/qruto/laravel-wave/blob/main/README.md

Replace the default Pusher configuration in resources/js/bootstrap.js with WaveConnector.

```diff
- import Echo from 'laravel-echo';

- import Pusher from 'pusher-js';
- window.Pusher = Pusher;

- window.Echo = new Echo({
-     broadcaster: 'pusher',
-     key: import.meta.env.VITE_PUSHER_APP_KEY,
-     wsHost: import.meta.env.VITE_PUSHER_HOST ?? `ws-${import.meta.env.VITE_PUSHER_APP_CLUSTER}.pusher.com`,
-     wsPort: import.meta.env.VITE_PUSHER_PORT ?? 80,
-     wssPort: import.meta.env.VITE_PUSHER_PORT ?? 443,
-     forceTLS: (import.meta.env.VITE_PUSHER_SCHEME ?? 'https') === 'https',
-     enabledTransports: ['ws', 'wss'],
- });
+ import Echo from 'laravel-echo';

+ import { WaveConnector } from 'laravel-wave';

+ window.Echo = new Echo({ broadcaster: WaveConnector });
```

--------------------------------

### Set BROADCAST_DRIVER to redis in .env

Source: https://github.com/qruto/laravel-wave/blob/main/README.md

Configure the .env file to use the redis broadcasting driver.

```ini
BROADCAST_DRIVER = redis
```

--------------------------------

### echo(): void

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/sse-server-sent-event.md

Alias for invoking the instance, which echoes and flushes the SSE frame.

```APIDOC
## echo(): void

### Description
Alias for `$this()`. Echoes the SSE frame and flushes the output buffer.

### Signature
```php
public function echo(): void
```

### Example
```php
$frame->echo();
```
```

--------------------------------

### Run tests with composer test

Source: https://github.com/qruto/laravel-wave/blob/main/README.md

Use this command to run the test suite for the Laravel Wave package.

```bash
composer test
```

--------------------------------

### Direct membership control with PresenceChannelUsersRepository

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/storage-presence-channel-users-repository.md

Shows how to use join(), getUsers(), and removeConnection() directly. join() returns true on first join and false when the user already had a connection. removeConnection() returns an array of ['channel', 'user_info'] maps for channels where the user fully exited.

```php
use Qruto\Wave\Storage\PresenceChannelUsersRepository;

/** @var PresenceChannelUsersRepository $repo */
$repo = app(PresenceChannelUsersRepository::class);

$first = $repo->join('presence-lobby', $user, ['id' => 1, 'name' => 'Ada'], '111.111');
// true on first join, false when the user already had a connection

$users = $repo->getUsers('presence-lobby');
// [['id' => 1, 'name' => 'Ada'], ...]

$exited = $repo->removeConnection($user, '111.111');
// [['channel' => 'presence-lobby', 'user_info' => ['id'=>1,'name'=>'Ada']]]
```

--------------------------------

### ConfigPublishCommand getBaseConfigurationFiles method

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/console-commands.md

Overrides Laravel's getBaseConfigurationFiles to add Wave's broadcasting config. Used by config:publish to publish the redis-first variant.

```php
protected function getBaseConfigurationFiles(): array
{
    return [
        'broadcasting' => realpath(__DIR__.'/../../../config/broadcasting.php'),
    ] + parent::getBaseConfigurationFiles();
}
```

--------------------------------

### Manual usage with WaveConnector

Source: https://github.com/qruto/laravel-wave/blob/main/README.md

Import Laravel Echo with WaveConnector and pass it to the broadcaster option.

```javascript
import Echo from 'laravel-echo';

import { WaveConnector } from 'laravel-wave';

window.Echo = new Echo({broadcaster: WaveConnector});
```

--------------------------------

### Lua script for join() method

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/storage-presence-channel-users-repository.md

Atomic Lua script executed via $this->db->eval() for the join() method. Returns 1 only when the user had no prior connection in the channel (firstJoin), which is used to decide whether to broadcast PresenceChannelJoinEvent->toOthers().

```lua
local firstJoin = redis.call('hexists', KEYS[1], ARGV[1]) == 0
redis.call('sadd', KEYS[2], ARGV[3])
redis.call('hset', KEYS[1], ARGV[1], ARGV[2])
redis.call('sadd', KEYS[3], ARGV[4])
return firstJoin and 1 or 0
```

--------------------------------

### Redis subscription connection clone in registeringPackage

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/wave-service-provider.md

Creates a dedicated Redis connection named '{name}-subscription' by cloning the main broadcasting Redis connection config. RedisSubscriber uses it for blocking psubscribe so the subscribed connection is never reused for other commands.

```php
$redisConnectionName = config('broadcasting.connections.redis.connection');
config()->set("database.redis.$redisConnectionName-subscription", config("database.redis.$redisConnectionName"));
```

--------------------------------

### Default PresenceChannelEventHandler implementation

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/presence-channel-event.md

Default implementation of the PresenceChannelEvent interface. isLeaveEvent returns true when the event name is 'leave' and the channel starts with 'presence-'. isSelfLeaveEvent uses loose comparison for userId. formatLeaveEventForSending replaces event data with userInfo.

```php
class PresenceChannelEventHandler implements PresenceChannelEvent
{
    public function isLeaveEvent(BroadcastingEvent $event, Authenticatable $user): bool
    {
        return $event->name === 'leave' && $this->fromPresenceChannel($event);
    }

    public function isSelfLeaveEvent(BroadcastingEvent $event, Authenticatable $user): bool
    {
        return $this->isLeaveEvent($event, $user) && $event->data['userId'] == $user->getAuthIdentifierForBroadcasting();
    }

    public function fromPresenceChannel(BroadcastingEvent $event): bool
    {
        return str_starts_with($event->channel, 'presence-');
    }

    public function formatLeaveEventForSending(BroadcastingEvent $event)
    {
        $event->data = $event->data['userInfo'];
    }
}
```

--------------------------------

### ServeCommand handle() method with SSE worker prompt

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/console-commands.md

Overrides the built-in Laravel serve command to increase concurrent connections for SSE. Reads PHP_CLI_SERVER_WKERS (default 1); if it is 1 and WaveServiceProvider is registered, prompts the developer to select worker count (leave 1, 10, or 20, default 10), sets the environment variable, and optionally appends it to .env. Otherwise delegates to the parent handle().

```php
public function handle()
{
    $workersAmount = env('PHP_CLI_SERVER_WORKERS', 1);

    if ($workersAmount === 1 && $this->getLaravel()->getProviders(WaveServiceProvider::class) !== []) {
        $workersAmount = (int) select(
            label: 'Looks like you are using Server-sent Events (SSE) for broadcasting. Set the preferable amount of workers.',
            options: ['leave 1 (default)', '10', '20'],
            default: 10,
            hint: 'The number of workers determines the maximum number of concurrent connections.',
        );

        $_ENV['PHP_CLI_SERVER_WORKERS'] = $workersAmount;
        putenv("PHP_CLI_SERVER_WORKERS={$workersAmount}");

        if (confirm('Do you want to save preferable amount to the .env file?', false)) {
            $file = base_path('.env');

            if (file_exists($file)) {
                file_put_contents(
                    $file,
                    (str_ends_with(file_get_contents($file), PHP_EOL) ? '' : PHP_EOL).
                    PHP_EOL."PHP_CLI_SERVER_WORKERS=$workersAmount".PHP_EOL,
                    FILE_APPEND
                );
            }
        }
    }

    return parent::handle();
}
```

--------------------------------

### SsePingCommand handle() method

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/console-commands.md

Handles the sse:ping command. Without --interval, fires a single SsePingEvent. With a non-zero interval, loops forever, pinging and sleeping the specified seconds. Outputs a two-column detail with a PINGED status.

```php
public function handle()
{
    $interval = (int) $this->option('interval');

    if ($interval !== 0) {
        while (true) {
            event(new SsePingEvent);

            $this->components->twoColumnDetail('<fg=gray>'.now().'</> SSE Wave Connections', '<fg=green;options=bold>PINGED</>');

            sleep($interval);
        }
    } else {
        $this->components->twoColumnDetail('<fg=gray>'.now().'</> SSE Wave Connections', '<fg=green;options=bold>PINGED</>');

        event(new SsePingEvent);
    }
}
```

--------------------------------

### Custom leave payload handling with MyLeavePolicy

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/presence-channel-event.md

Example of a custom PresenceChannelEvent implementation that overrides the default handler. It customizes the leave payload format and uses getAuthIdentifier() instead of getAuthIdentifierForBroadcasting(). Register it in a service provider with bind to override the package default.

```php
use Qruto\Wave\PresenceChannelEvent;
use Qruto\Wave\Storage\BroadcastingEvent;

class MyLeavePolicy implements PresenceChannelEvent
{
    public function isLeaveEvent(BroadcastingEvent $event, \Illuminate\Contracts\Auth\Authenticatable $user): bool
    {
        return $event->name === 'leave' && str_starts_with($event->channel, 'presence-');
    }

    public function isSelfLeaveEvent(BroadcastingEvent $event, \Illuminate\Contracts\Auth\Authenticatable $user): bool
    {
        return $this->isLeaveEvent($event, $user)
            && $event->data['userId'] == $user->getAuthIdentifier();
    }

    public function fromPresenceChannel(BroadcastingEvent $event): bool
    {
        return str_starts_with($event->channel, 'presence-');
    }

    public function formatLeaveEventForSending(BroadcastingEvent $event)
    {
        // custom reshape of the outgoing leave payload
        $event->data = ['user' => $event->data['userInfo']];
    }
}

// register in a service provider (overrides the package default $this->app->bind):
$this->app->bind(PresenceChannelEvent::class, MyLeavePolicy::class);
```

--------------------------------

### Constructor closure middleware for auth and user info

Source: https://github.com/qruto/laravel-wave/blob/main/_autodocs/api-reference/http-presence-channel-users-controller.md

Registers a closure middleware that runs before every action. Calls Broadcast::auth($request) to run the channel authorization callback; throws AccessDeniedHttpException (403) when unauthorized. Decodes the auth response and stores channel_data.user_info in $this->userInfo. Copies socket_id query/body parameter to X-Socket-Id header so Broadcast::socket($request) returns the client's connection id.

```php
$this->middleware((function ($request, $next) {
    $this->userInfo = json_decode(Broadcast::auth($request), true, 512, JSON_THROW_ON_ERROR)['channel_data']['user_info'];

    if ($request->has('socket_id')) {
        $request->headers->set('X-Socket-Id', $request->socket_id);
    }

    return $next($request);
}));
```
Tokens:
Raw