Laravel Reverb

https://github.com/laravel/reverb
Admin
Laravel Reverb provides a real-time WebSocket communication backend for Laravel applications,...
Tokens:85,960
Snippets:626
Trust Score:9.7
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example — constructing an app manually

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/core.md

Example of manually constructing an Application instance using named arguments. Shows how to check if rate limiting is enabled with usesRateLimiting().

```php
use Laravel\Reverb\Application;

$app = new Application(
    id: '123456',
    key: 'reverb-key',
    secret: 'reverb-secret',
    pingInterval: 60,
    activityTimeout: 30,
    allowedOrigins: ['*'],
    maxMessageSize: 10_000,
);

if ($app->usesRateLimiting()) {
    // rate limiting enabled via $app->rateLimiting()
}
```

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

### InstallCommand class for reverb:install

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

Defines the artisan command 'reverb:install' with its signature and description. The handle method is declared but its body is not shown in the source.

```php
#[AsCommand(name: 'reverb:install')]
class InstallCommand extends Command
{
    protected $signature = 'reverb:install';
    protected $description = 'Install the Reverb dependencies';
    public function handle(): void
}
```

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

### Starting the server and checking the driver

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/core.md

Shows how to start the server and check the driver. It resolves the 'reverb' driver via the manager, then if the driver subscribes to events (indicating Redis scaling mode is active), it connects the pub/sub bridge using the PubSubProvider and the event loop.

```php
use Laravel\Reverb\ServerProviderManager;

$manager = app(ServerProviderManager::class);

$driver = $manager->driver('reverb'); // ReverbServerProvider

if ($driver->subscribesToEvents()) {
    // Redis scaling mode is active; connect the pub/sub bridge.
    app(PubSubProvider::class)->connect(Loop::get());
}
```

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

### Run reverb:install command

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

Runs the reverb:install artisan command. The expected output is 'Reverb installed successfully.'

```bash
php artisan reverb:install
# > Reverb installed successfully.
```

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

### Start Reverb server with debug output

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

Starts the Reverb server with a custom host and port, enabling debug output. The expected output line is shown as a comment.

```bash
php artisan reverb:start --host 0.0.0.0 --port 8080 --debug
# > Starting server on 0.0.0.0:8080
```

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

### Log static proxy usage example

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

Example of using the Log facade statically to log info and messages, and binding a custom logger implementation.

```php
use Laravel\Reverb\Loggers\Log;

Log::info('Connection Established', $connection->id());
Log::message($rawFrame);

// Custom logger: bind your own implementation
$app->instance(Logger::class, new MyLogger);
```

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

### Programmatic Server Usage Example

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/pusher-server.md

Example of driving the server programmatically, as the tests feature suite does. Shows constructing the server, opening a connection, sending a malformed message (which results in a pusher:error 4200 frame), handling a control frame, and closing the connection.

```php
use Laravel\Reverb\Protocols\Pusher\Server;

$server = new Server(app(ChannelManager::class), new EventHandler(app(ChannelManager::class)));

// Accept a connection; on failure an error payload is written to the wire.
$server->open($connection);

// A malformed message results in a pusher:error 4200 frame, never an exception escaping.
$server->message($connection, 'not json at all');

$server->control($connection, $pingFrame); // marks connection as using control frames
$server->close($connection);
```

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

### Route usage example

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/server.md

Example of registering health check and broadcast routes using the Route::get and Route::post static methods.

```php
use Laravel\Reverb\Servers\Reverb\Http\Route;

$routes->add('health_check', Route::get('/up', new HealthCheckController));
$routes->add('broadcast', Route::post('/apps/{appId}/events', new EventsController));
```

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

### Define reverb:start command signature

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

Defines the reverb:start command signature and description. The signature includes options for host, port, path, hostname, and debug, with defaults pulled from the reverb.servers.reverb configuration.

```php
#[AsCommand(name: 'reverb:start')]
protected $signature = 'reverb:start
            {--host= : The IP address the server should bind to}
            {--port= : The port the server should listen on}
            {--path= : The path the server should prefix to all routes}
            {--hostname= : The hostname the server is accessible from}
            {--debug : Indicates whether debug messages should be displayed in the terminal}';
protected $description = 'Start the Reverb server';
```

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

### Control frames example

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/connections.md

Shows enabling control frame usage and sending a ping control frame.

```php
// After the peer sends any RFC6455 control frame the protocol marks usage:
$conn->setUsesControlFrames();

// Subsequent pings go out as RFC6455 ping frames instead of Pusher `ping` events:
$conn->control(); // Frame::OP_PING
```

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

### Channel usage example

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/channels.md

Example usage of the Channel class: create a channel, subscribe a connection with data, broadcast a message excluding the sender, and unsubscribe.

```php
use Laravel\Reverb\Protocols\Pusher\Channels\Channel;

$channel = new Channel('chat.1');
$channel->subscribe($conn, data: '{"user_id":"user-1"}');

$channel->broadcast(
    ['event' => 'message', 'data' => '{"text":"hi"}'],
    except: $conn,           // sender does not receive its own message
);

$channel->unsubscribe($conn);
```

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

### Connection lifecycle example

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/connections.md

Shows creating a Connection, marking it active, sending a message, and terminating if inactive and pinged.

```php
use Laravel\Reverb\Connection;

$conn = new Connection($rawSocket, $app, 'https://example.com');

$conn->touch();                    // mark active now
$conn->send('{"event":"pusher:pong"}');

if ($conn->isInactive() && $conn->hasBeenPinged) {
    // stale — PusherServer::close + channels->unsubscribeFromAll happen upstream
    $conn->terminate();
}
```

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

### Programmatic server startup with Factory::make

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/server.md

Programmatic server startup using Factory::make with named arguments. Shows how to catch the InvalidArgumentException for an unsupported protocol and that start() blocks while running the event loop.

```php
use Laravel\Reverb\Servers\Reverb\Factory;

$server = Factory::make(
    host: '127.0.0.1',
    port: '8080',
    path: '/reverb',
    hostname: 'reverb.test',
    maxRequestSize: 10_000,
);

// Error handling: unsupported protocol
try {
    Factory::make(protocol: 'bogus');
} catch (InvalidArgumentException $e) {
    // "Unsupported protocol [bogus]."
}

$server->start(); // blocking; runs the event loop
```

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

### ServerProviderManager and ReverbServerProvider

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/core.md

Documentation for the ServerProviderManager and ReverbServerProvider classes, including their constructors, methods, and usage example.

```APIDOC
## ServerProviderManager

### Description
Manager that resolves the configured server driver (e.g. `reverb` → `ReverbServerProvider`). Extends `Illuminate\Support\Manager`.

### Methods

#### `__construct(protected Application $app)`

#### `createReverbDriver(): ReverbServerProvider`

Returns `new ReverbServerProvider($this->app, $this->config->get('reverb.servers.reverb', []))`.

#### `getDefaultDriver(): string`

Returns `$this->config->get('reverb.default', 'reverb')`.

### Source Refs
- `src/ServerProviderManager.php:14`, `:22`, `:33`

## ReverbServerProvider

### Description
The concrete server driver, `extends Laravel\Reverb\Contracts\ServerProvider`.

### Methods

#### `__construct(protected Application $app, protected array $config)`

Sets `$this->publishesEvents = (bool) $this->config['scaling']['enabled'] ?? false;` — note the precedence: the null-coalescing `?? false` applies after the cast, so a missing `scaling` key produces `false`; `scaling.enabled=true` produces `true`.

#### `register(): void`

Binds `Laravel\Reverb\Servers\Reverb\Contracts\PubSubProvider::class` as a singleton closure: `new RedisPubSubProvider($app->make(RedisClientFactory::class), $app->make(PubSubIncomingMessageHandler::class), $this->config['scaling']['channel'] ?? 'reverb', $this->config['scaling']['server'] ?? [])`. This binding is registered with `singletonIf`-style semantics upstream so user-defined bindings win (CHANGELOG v1.10.0).

#### `boot(): void`

In console mode, resolves console commands `StartServer::class` and `RestartServer::class` via `Artisan::starting(...)`.

#### `withPublishing(): void`

Enables event publishing programmatically.

#### `shouldPublishEvents(): bool`

Returns the resolved publishing flag. Also `subscribesToEvents()`, `shouldNotPublishEvents()`, `doesNotSubscribeToEvents()` inherited from `ServerProvider`.

### Source Refs
- `src/Servers/Reverb/ReverbServerProvider.php:27`, `:35`, `:48`, `:63`, `:71`

### Example — starting the server and checking the driver

```php
use Laravel\Reverb\ServerProviderManager;

$manager = app(ServerProviderManager::class);

$driver = $manager->driver('reverb'); // ReverbServerProvider

if ($driver->subscribesToEvents()) {
    // Redis scaling mode is active; connect the pub/sub bridge.
    app(PubSubProvider::class)->connect(Loop::get());
}
```

### Related
- [configuration.md](../configuration.md) for `reverb.servers.reverb` and `reverb.apps.*` keys; [server.md](server.md) for `Factory::make()` and the HTTP layer; [errors.md](../errors.md).
```

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

### Environment variables added by reverb:install

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

Environment variables appended to the app's .env file by the install command. Only missing keys are added; values are generated randomly as indicated.

```plaintext
REVERB_APP_ID=<random 6-digit int>
REVERB_APP_KEY=<lowercase random 20 chars>
REVERB_APP_SECRET=<lowercase random 20 chars>
REVERB_HOST="localhost"
REVERB_PORT=8080
REVERB_SCHEME=http
VITE_REVERB_APP_KEY="${REVERB_APP_KEY}"
VITE_REVERB_HOST="${REVERB_HOST}"
VITE_REVERB_PORT="${REVERB_PORT}"
VITE_REVERB_SCHEME="${REVERB_SCHEME}"
```

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

### curl example for POST /apps/{appId}/events

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/http-controllers.md

Example curl command to trigger the EventsController endpoint. It posts an event to a channel and expects a 200 response with an empty JSON object.

```bash
curl -X POST 'http://localhost:8080/apps/123456/events?auth_key=reverb-key&auth_timestamp=1700000000&auth_version=1.0&auth_signature=<hmac>' \
     -d '{"name":"message","channel":"chat.1","data":"{\"body\":\"hi\"}"}'
# 200 -> {}
```

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

### Using Certificate::exists and resolve

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

Example usage of the Certificate helper. Checks if a certificate exists for a hostname and resolves its paths for use in a TLS context.

```php
use Laravel\Reverb\Certificate;

if (Certificate::exists('reverb.test')) {
    [$cert, $key] = Certificate::resolve('reverb.test');
    // cert/key paths for the TLS context
}
```

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

### Reverb::registerDevCommands()

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/core.md

Static method to register the reverb:start artisan command as a dev command.

```APIDOC
## Reverb::registerDevCommands()

### Description
Registers the `reverb:start` artisan command as a Laravel dev command. This is a static method that can be called directly, though it is typically invoked automatically by the service provider.

### Method
`registerDevCommands`

### Signature
```php
public static function registerDevCommands(): void
```

### Parameters
None

### Returns
`void`

### Behavior
If the `Illuminate\Foundation\DevCommands` class exists at runtime, registers `reverb:start` as a dev command named `reverb`.

### Example
```php
use Laravel\Reverb\Reverb;

// Called automatically by the service provider; also callable directly.
Reverb::registerDevCommands();
```
```

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

### GET /up

Source: https://github.com/laravel/reverb/blob/main/_autodocs/endpoints.md

Unauthenticated health probe to check if the service is running.

```APIDOC
## GET /up

### Description
Unauthenticated health probe to check if the service is running.

### Method
GET

### Endpoint
/up

### Response
#### Success Response (200)
- **health** (string) - Always "OK".

#### Response Example
{
  "health": "OK"
}
```

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

### Example: gather with error fallback

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/metrics.md

Shows how to gather presence data in scaling mode with a fallback to the channel's data on aggregation failure.

```php
use Laravel\Reverb\Protocols\Pusher\MetricsHandler;

// Presence flow from EventHandler (scaling mode):
app(MetricsHandler::class)
    ->gather($app, 'presence_data', ['channel' => 'presence-online'])
    ->catch(fn () => $channel->data())                       // fallback on aggregation failure
    ->then(fn (array $data) => sendSubscriptionSucceeded($channel, $connection, $data));
```

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

### Wiring a raw WebSocket connection

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/connections.md

Shows how to wire a raw connection, as done in PusherController::__invoke(). It sets the max message size, registers message/control/close handlers, and then calls openBuffer() to start processing.

```php
use Laravel\Reverb\Servers\Reverb\Connection;

$socket = new Connection($httpConnection);

$socket->withMaxMessageSize($app->maxMessageSize());
$socket->onMessage(fn ($message) => $server->message($reverbConnection, (string) $message));
$socket->onControl(fn (FrameInterface $message) => $server->control($reverbConnection, $message));
$socket->onClose(fn () => $server->close($reverbConnection));

$socket->openBuffer();
```

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

### GET /app/{appKey}

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/http-controllers.md

WebSocket upgrade endpoint that resolves the application by key and establishes a connection. On invalid application, it sends an error frame and closes the connection.

```APIDOC
## GET /app/{appKey}

### Description
WebSocket upgrade endpoint that resolves the application by key and establishes a connection. On invalid application, it sends an error frame and closes the connection.

### Method
GET

### Endpoint
/app/{appKey}

### Parameters
#### Path Parameters
- **appKey** (string) - Required - The application key.

### Response
#### Success Response (101 Switching Protocols)
Upgrades to WebSocket connection.

#### Error Response (4001)
Sends raw frame: `{"event":"pusher:error","data":"{\"code\":4001,\"message\":\"Application does not exist\"}"}` and closes the connection.

```

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

### Example: consumer of a REST trigger

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/metrics.md

Shows the expected response for a REST trigger that calls gather with 'channel_users'.

```php
// GET /apps/{appId}/channels/{channel}/users triggers:
// MetricsHandler::gather($app, 'channel_users', ['channel' => 'presence-online'])
// -> {"users":[{"id":"1"},{"id":"2"}]}
```

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

### REST error-handling example with HTTP status codes

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/http-controllers.md

Error-handling example for REST consumers. Shows expected HTTP status codes and JSON error messages for bad/expired signature (401), unknown app id (404), and validation errors (422). Notes that HttpException is serialized as {statusCode, message}.

```php
// 401 — bad or expired signature
// {"message":"Authentication signature invalid."} with HTTP 401

// 404 — unknown app id
// {"message":"No matching application for ID [nope]."}

// 422 — validation errors (EventsController)
// {"name":["The name field is required."], ...}

// The HTTP layer serializes HttpException as {statusCode, message}; see server.md.
```

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

### Using Log facade for debug logging

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/core.md

Shows how to use the Log facade to write log messages, which proxies to the container-bound Logger instance. By default this is NullLogger; the reverb:start --debug command rebinds it to CliLogger.

```php
// app(Logger::class) resolves to NullLogger by default.
// The `reverb:start --debug` command rebinds it to CliLogger.

// Later, from any context:
use Laravel\Reverb\Loggers\Log;

Log::info('Connection Established', $connection->id()); // proxies to app(Logger::class)
```

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

### Observing traffic with MessageSent event

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

Example comment showing how to listen to MessageSent events and the event payload structure.

```php
// app()->listen(MessageSent::class, ...) via the host framework; e.g. a Laravel event listener
// Event payload: {connection: Laravel\Reverb\Connection, message: "<raw frame json>"}
// MessageReceived bytes flow: ClientEvent / EventHandler -> Server::message -> MessageReceived::dispatch
```

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

### Embedding Reverb in a custom pub/sub relay

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/redis.md

Example of using RedisPubSubProvider to connect to the bus, listen for custom events, and publish a message. The publish promise rejects if the client is disconnected, and the error can be caught.

```php
use Laravel\Reverb\Servers\Reverb\Publishing\RedisPubSubProvider;

$bus = app(PubSubProvider::class); // RedisPubSubProvider singleton

$bus->connect(Loop::get());

$bus->on('custom-event', fn ($event) => {
    // $event is the full decoded bus payload array
});

// Bus rejection path (RedisPublishClient while disconnected): promise rejects.
$bus->publish(['type' => 'message', 'application' => serialize($app), 'payload' => $payload])
    ->catch(fn ($e) => Log::error('Could not publish; event queued.'));
```

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

### Echo wiring for internal server bus

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/pusher-server.md

Example of wiring the EventHandler for an internal server bus. Shows subscribing to a presence channel with an auth signature, handling raw Pusher events, and sending a hand-rolled payload with the resulting JSON output.

```php
use Laravel\Reverb\Protocols\Pusher\EventHandler;

$handler = new EventHandler(app(ChannelManager::class));

$handler->subscribe($connection, 'presence-online', auth: '1234.5678:hmac-signature');

// Raw event handling (payload keys match the Pusher protocol):
$handler->handle($connection, 'pusher:ping');
$handler->handle($connection, 'pusher:unsubscribe', ['channel' => 'presence-online']);

// Hand-rolled payloads:
$handler->send($connection, 'message', ['body' => 'hi'], 'chat.1');
// -> {"event":"pusher:message","data":"{\"body\":\"hi\"}","channel":"chat.1"}
```

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

### GET /apps/{appId}/channels/{channel}

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/http-controllers.md

Retrieves channel metrics including occupancy information.

```APIDOC
## GET /apps/{appId}/channels/{channel}

### Description
Retrieves metrics for a specific channel, including occupancy information.

### Method
GET

### Endpoint
/apps/{appId}/channels/{channel}

### Parameters
#### Path Parameters
- **appId** (string) - Required - The application ID.
- **channel** (string) - Required - The channel name.

#### Query Parameters
- **info** (string) - Optional - Comma-separated list of channel info fields to include. The 'occupied' field is always included.

### Response
#### Success Response (200)
Returns a channel info object, e.g., `{"occupied":true,"user_count":3}`.

#### Response Example
```json
{"occupied":true,"user_count":3}
```
```

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

### Reverb broadcasting connection configuration

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

Configuration block injected into config/broadcasting.php by the install command, unless a 'reverb' connection already exists. It uses environment variables for connection settings.

```php
'reverb' => [
    'driver' => 'reverb',
    'key' => env('REVERB_APP_KEY'),
    'secret' => env('REVERB_APP_SECRET'),
    'app_id' => env('REVERB_APP_ID'),
    'options' => [
        'host' => env('REVERB_HOST'),
        'port' => env('REVERB_PORT', 443),
        'scheme' => env('REVERB_SCHEME', 'https'),
        'useTLS' => env('REVERB_SCHEME', 'https') === 'https',
        'path' => env('REVERB_SERVER_PATH', ''),
    ],
    'client_options' => [
        // Guzzle client options
    ],
],
```

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

### Reverb::registerDevCommands() method signature

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/core.md

Registers the reverb:start artisan command as a dev command named 'reverb' if the Illuminate\Foundation\DevCommands class exists. Called automatically from ReverbServiceProvider::register().

```php
public static function registerDevCommands(): void
```

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

### Route class public methods

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/server.md

Lists the constructor and all static HTTP verb methods (get, post, put, patch, delete, head, connect, options, trace) that return Symfony BaseRoute instances.

```php
public function __construct(string $path)
public static function get(string $path, callable $action): BaseRoute
public static function post($path, callable $action): BaseRoute
public static function put($path, callable $action): BaseRoute
public static function patch($path, callable $action): BaseRoute
public static function delete($path, callable $action): BaseRoute
public static function head($path, callable $action): BaseRoute
public static function connect($path, callable $action): BaseRoute
public static function options($path, callable $action): BaseRoute
public static function trace($path, callable $action): BaseRoute
```

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

### Direct channel manager interaction example

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/channels.md

Shows direct interaction with the channel manager. Retrieves the manager for an app, creates a presence channel, subscribes a connection, counts connections, finds a connection by socket id, and unsubscribes from all. Comments note lifecycle events: ChannelCreated dispatched on findOrCreate, ChannelRemoved on remove (auto-remove when empty).

```php
use Laravel\Reverb\Protocols\Pusher\Managers\ArrayChannelManager;

$manager = app(ChannelManager::class)->for($app);

$channel = $manager->findOrCreate('presence-online');   // PresenceChannel via ChannelBroker
$channel->subscribe($conn, '1234.5678:token', '{"user_id":"1"}');

$count = count($manager->connections());                // across all channels
$conn  = $manager->findConnection('1234.5678');         // by socket id
$manager->unsubscribeFromAll($conn);

// Lifecycle hooks (Illuminate Dispatchable events):
// ChannelCreated::dispatch($channel)          — on findOrCreate
// ChannelRemoved::dispatch($channel)          — on remove (auto-remove when empty)
```

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

### EventDispatcher::dispatch - Server-side broadcast example

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/pusher-server.md

Shows how to use EventDispatcher::dispatch for local (non-scaling) delivery and with socket exclusion (to_others semantics). The payload follows the internal message shape with 'event', 'channels', and 'data'. The socketId is included only when non-null, defaulting to the connection id.

```php
use Laravel\Reverb\Protocols\Pusher\EventDispatcher;

// Local (non-scaling) delivery:
EventDispatcher::dispatch($app, [
    'event' => 'message',
    'channels' => ['chat.1', 'chat.2'],
    'data' => ['body' => 'hello world'],
], $exceptConnection);

// With socket exclusion (to_others semantics):
EventDispatcher::dispatch($app, $payload, except: $connection, socketId: $connection->id());
```

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

### ReverbServiceProvider::boot() method signature

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/core.md

Registers the InstallCommand, publishes config/reverb.php with tags ['reverb', 'reverb-config'], registers reverb:restart as a config reload command, loads Pulse views and Livewire components, and delegates to ServerProviderManager::boot().

```php
public function boot(): void
```

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

### ReverbServiceProvider::boot()

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/core.md

Boot method for the service provider, handling console commands, config publishing, and Pulse integration.

```APIDOC
## ReverbServiceProvider::boot()

### Description
Boots the service provider: registers console commands, publishes configuration, loads views and Livewire components when Pulse is present, and delegates to the server provider manager's boot method.

### Method
`boot`

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

### Parameters
None

### Returns
`void`

### Behavior
- When running in the console: registers the `InstallCommand`, publishes `config/reverb.php` under tags `['reverb', 'reverb-config']`, and registers `reverb:restart` as a config reload command.
- When `Laravel\Pulse\Pulse` is bound: loads Blade views from `resources/views` under the `reverb` namespace and registers Livewire components `reverb.messages` and `reverb.connections`.
- Delegates to `ServerProviderManager::boot()`.
```

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

### Create server with ServerFactory::make

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

Builds the Reverb server using ServerFactory::make with the host, port, path, hostname, and configuration options. The loop parameter is passed for event loop integration.

```php
$server = ServerFactory::make(
    host, port, path, hostname,
    $config['max_request_size'] ?? 10_000,
    $config['options'] ?? [],
    loop: $loop
);
```

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

### GET /apps/{appId}/channels/{channel}

Source: https://github.com/laravel/reverb/blob/main/_autodocs/endpoints.md

Retrieves information about a specific channel.

```APIDOC
## GET /apps/{appId}/channels/{channel}

### Description
Retrieves information about a specific channel. The `occupied` key is always included in the response.

### Method
GET

### Endpoint
/apps/{appId}/channels/{channel}

### Parameters
#### Path Parameters
- **appId** (string) - Required - The unique identifier of the application.
- **channel** (string) - Required - The name of the channel.

#### Query Parameters
- **info** (string) - Optional - Comma-separated list of info keys to include. `occupied` is always included.

### Response
#### Success Response (200)
- **occupied** (boolean) - Whether the channel has active subscribers.
- **user_count** (int) - Optional - Number of users subscribed (if requested).

#### Response Example
{
  "occupied": true,
  "user_count": 3
}
```

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

### ConfigApplicationProvider method signatures

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/core.md

Lists the public methods of ConfigApplicationProvider: the constructor accepts a Collection of application rows, all() returns the collection of Application instances, findById and findByKey locate by 'app_id' or 'key', and find() performs a firstWhere lookup, throwing InvalidApplication when no match is found.

```php
public function __construct(protected Collection $applications)
public function all(): Collection                       // Collection<Application>
public function findById(string $id): Application       // find('app_id', $id)
public function findByKey(string $key): Application      // find('key', $key)
public function find(string $key, mixed $value): Application
```

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

### GET /apps/{appId}/connections

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/http-controllers.md

Returns the number of connections for the given application.

```APIDOC
## GET /apps/{appId}/connections

### Description
Returns the number of connections for the given application.

### Method
GET

### Endpoint
/apps/{appId}/connections

### Parameters
#### Path Parameters
- **appId** (string) - Required - The application ID.

### Response
#### Success Response (200)
- **connections** (int) - The number of connections.

#### Response Example
{
  "connections": 42
}
```

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

### Resolving and guarding an application

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/core.md

Shows how to resolve the default ConfigApplicationProvider from the container, perform a basic lookup with findByKey, and catch InvalidApplication when findById fails, with the exception message 'Application does not exist'.

```php
use Laravel\Reverb\ConfigApplicationProvider;
use Laravel\Reverb\Exceptions\InvalidApplication;

$provider = app(ApplicationProvider::class); // ConfigApplicationProvider by default

// Basic lookup
$app = $provider->findByKey('reverb-key');

// Error handling
try {
    $app = $provider->findById('does-not-exist');
} catch (InvalidApplication $e) {
    // $e->getMessage() === 'Application does not exist'
}
```

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

### ReverbServerProvider public method signatures

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/core.md

Lists the public methods of the ReverbServerProvider class. The constructor sets the publishesEvents flag based on the 'scaling.enabled' config, register() binds the PubSubProvider singleton, boot() resolves console commands in console mode, and withPublishing() enables event publishing.

```php
public function __construct(protected Application $app, protected array $config)
public function register(): void
public function boot(): void
public function withPublishing(): void
public function shouldPublishEvents(): bool
```

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

### GET /apps/{appId}/channels

Source: https://github.com/laravel/reverb/blob/main/_autodocs/endpoints.md

Retrieves a list of channels with active subscribers for the specified app.

```APIDOC
## GET /apps/{appId}/channels

### Description
Retrieves a list of channels with active subscribers for the specified app. Supports filtering by prefix and requesting additional info.

### Method
GET

### Endpoint
/apps/{appId}/channels

### Parameters
#### Path Parameters
- **appId** (string) - Required - The unique identifier of the application.

#### Query Parameters
- **filter_by_prefix** (string) - Optional - Only return channels starting with this prefix.
- **info** (string) - Optional - Comma-separated list of info keys to include in the response.

### Response
#### Success Response (200)
- **channels** (object) - An object mapping channel names to their info objects.

#### Response Example
{
  "channels": {
    "channel1": {
      "occupied": true
    }
  }
}
```

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

### ApplicationManager and ConfigApplicationProvider

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/core.md

Documentation for the ApplicationManager and ConfigApplicationProvider classes, including their public methods and configuration defaults.

```APIDOC
## ApplicationManager

`src/ApplicationManager.php`

Controller-style manager (`extends Illuminate\Support\Manager`) that resolves the configured `ApplicationProvider` driver.

### Methods

#### `createConfigDriver(): ConfigApplicationProvider`

Returns a new `ConfigApplicationProvider` instance built from the `reverb.apps.apps` configuration array.

#### `getDefaultDriver(): string`

Returns the configured default driver name from `reverb.apps.provider` (defaults to `'config'`).

## ConfigApplicationProvider

`src/ConfigApplicationProvider.php` — implements `Laravel\Reverb\Contracts\ApplicationProvider`.

Reads the `reverb.apps.apps` config array (list of app row arrays) and constructs `Application` instances.

### Constructor

`__construct(protected Collection $applications)`

### Methods

#### `all(): Collection`

Returns a collection of all `Application` instances.

#### `findById(string $id): Application`

Finds an application by its `app_id`.

#### `findByKey(string $key): Application`

Finds an application by its `key`.

#### `find(string $key, mixed $value): Application`

Finds an application by an arbitrary key-value pair. Throws `InvalidApplication` if no match is found.

### Defaults Applied to Missing Row Keys

| Row key | Mapped constructor arg | Default |
|---------|------------------------|---------|
| app_id | id | (required by finder) |
| key | key | — |
| secret | secret | — |
| ping_interval | pingInterval | — |
| activity_timeout | activityTimeout | 30 |
| allowed_origins | allowedOrigins | — |
| max_message_size | maxMessageSize | — |
| max_connections | maxConnections | null |
| accept_client_events_from | acceptClientEventsFrom | `'all'` |
| rate_limiting | rateLimiting | null |
| options | options | [] |

> **Note on defaults**: `config/reverb.php` ships `accept_client_events_from` defaulting to `'members'` (`REVERB_APP_ACCEPT_CLIENT_EVENTS_FROM`), but the provider falls back to `'all'` when the key is absent entirely.

### Example — Resolving and Guarding

```php
use Laravel\Reverb\ConfigApplicationProvider;
use Laravel\Reverb\Exceptions\InvalidApplication;

$provider = app(ApplicationProvider::class); // ConfigApplicationProvider by default

// Basic lookup
$app = $provider->findByKey('reverb-key');

// Error handling
try {
    $app = $provider->findById('does-not-exist');
} catch (InvalidApplication $e) {
    // $e->getMessage() === 'Application does not exist'
}
```
```

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

### Application

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/core.md

Documentation for the Application class, including its constructor, getters, and toArray method.

```APIDOC
## Application

### Description
Immutable value object describing a Reverb application (a Pusher-compatible app registry entry). Constructed directly, or by `ConfigApplicationProvider::find()`.

### Constructor

```php
public function __construct(
    protected string $id,
    protected string $key,
    protected string $secret,
    protected int $pingInterval,
    protected int $activityTimeout,
    protected array $allowedOrigins,
    protected int $maxMessageSize,
    protected ?int $maxConnections = null,
    protected string $acceptClientEventsFrom = 'members',
    protected ?array $rateLimiting = null,
    protected array $options = [],
)
```

#### Parameters
- **id** (string) - Required - Application ID (`app_id`), the Pusher app identifier used in REST paths and `toArray()`
- **key** (string) - Required - Application key, used to look up the app on WebSocket upgrade (`/app/{appKey}`)
- **secret** (string) - Required - Application secret, used to HMAC-SHA256 verify REST signatures and channel auth tokens
- **pingInterval** (int) - Required - Client ping interval in seconds (`ping_interval`)
- **activityTimeout** (int) - Required - Activity timeout in seconds (`activity_timeout`), sent to clients in `connection_established`
- **allowedOrigins** (array<int,string>) - Required - Allowed CORS origins; `'*'` allows any origin
- **maxMessageSize** (int) - Required - Maximum size (bytes) of client WebSocket messages
- **maxConnections** (?int) - Optional - Optional application-level connection limit (default: null)
- **acceptClientEventsFrom** (string) - Optional - `'all'`, `'members'`, or `'none'` — who may send `client-*` events (default: 'members')
- **rateLimiting** (?array) - Optional - Rate limit config (`enabled`, `max_attempts`, `decay_seconds`, `terminate_on_limit`) (default: null)
- **options** (array) - Optional - Opaque options passed through to the broadcasting client config (default: [])

### Getters

```php
public function id(): string
public function key(): string
public function secret(): string
public function allowedOrigins(): array       // array<int, string>
public function pingInterval(): int
public function activityTimeout(): int
public function maxConnections(): ?int
public function hasMaxConnectionLimit(): bool // maxConnections !== null
public function maxMessageSize(): int
public function acceptClientEventsFrom(): string
public function rateLimiting(): ?array
public function usesRateLimiting(): bool      // (rateLimiting['enabled'] ?? false) === true
public function options(): ?array
```

- All getters return the constructor value unchanged.
- `usesRateLimiting()` returns `true` only when the `enabled` key of the `rateLimiting` array is exactly `true` (missing key → `false`).

### `toArray(): array`

```php
/**
 * @return array<string, mixed>
 */
public function toArray(): array
```

Returns a Pusher-broadcasting-compatible configuration array:

| Key | Type | Description |
|-----|------|-------------|
| app_id | string | `id` |
| key | string | `key` |
| secret | string | `secret` |
| ping_interval | int | `pingInterval` |
| activity_timeout | int | `activityTimeout` |
| allowed_origins | array | `allowedOrigins` |
| max_message_size | int | `maxMessageSize` |
| options | array | `options` |

Note: `max_connections`, `accept_client_events_from`, and `rate_limiting` are **not** included in `toArray()`; it is consumed by the broadcasting layer only.

### Example — constructing an app manually

```php
use Laravel\Reverb\Application;

$app = new Application(
    id: '123456',
    key: 'reverb-key',
    secret: 'reverb-secret',
    pingInterval: 60,
    activityTimeout: 30,
    allowedOrigins: ['*'],
    maxMessageSize: 10_000,
);

if ($app->usesRateLimiting()) {
    // rate limiting enabled via $app->rateLimiting()
}
```

### Example — error path
`Application` itself throws nothing; errors surface in the providers that resolve it (see `ConfigApplicationProvider` below).
```

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

### GET /apps/{appId}/channels/{channel}/users

Source: https://github.com/laravel/reverb/blob/main/_autodocs/endpoints.md

Retrieves the list of users subscribed to a presence channel.

```APIDOC
## GET /apps/{appId}/channels/{channel}/users

### Description
Retrieves the list of users subscribed to a presence channel. Returns an error if the channel is not a presence channel or does not exist.

### Method
GET

### Endpoint
/apps/{appId}/channels/{channel}/users

### Parameters
#### Path Parameters
- **appId** (string) - Required - The unique identifier of the application.
- **channel** (string) - Required - The name of the channel.

### Response
#### Success Response (200)
- **users** (array) - List of user objects, each containing an `id`.

#### Response Example
{
  "users": [
    {
      "id": "user1"
    }
  ]
}

#### Error Response (400)
- **Body**: `[]` - Channel exists but is not a presence channel.

#### Error Response (404)
- **Body**: `[]` - No such channel.
```

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

### GET /apps/{appId}/connections

Source: https://github.com/laravel/reverb/blob/main/_autodocs/endpoints.md

Retrieve information about the connections for an application. Requires HMAC signature authentication.

```APIDOC
## GET /apps/{appId}/connections

### Description
Retrieve information about the connections for an application. Requires HMAC signature authentication.

### Method
GET

### Endpoint
/apps/{appId}/connections

### Parameters
#### Path Parameters
- **appId** (string) - Required - The application ID.

#### Query Parameters
- **auth_key** (string) - Required - Application key.
- **auth_timestamp** (integer) - Required - Unix seconds; must be within 600 seconds of server time.
- **auth_version** (string) - Required - Version string.
- **auth_signature** (string) - Required - Hex HMAC-SHA256 signature.

### Response
#### Success Response (200)
Connection information.

#### Error Response (401)
Authentication signature invalid.

```

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

### Application constructor with parameter promotion

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/core.md

Constructor for the Application class using PHP 8 parameter promotion. Each protected parameter becomes a private property; use the explicit getter methods to access them.

```php
public function __construct(
    protected string $id,
    protected string $key,
    protected string $secret,
    protected int $pingInterval,
    protected int $activityTimeout,
    protected array $allowedOrigins,
    protected int $maxMessageSize,
    protected ?int $maxConnections = null,
    protected string $acceptClientEventsFrom = 'members',
    protected ?array $rateLimiting = null,
    protected array $options = [],
)
```

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

### GET /apps/{appId}/channels

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/http-controllers.md

Lists channels for the application, optionally filtered by prefix and with channel info.

```APIDOC
## GET /apps/{appId}/channels

### Description
Lists channels for the application, optionally filtered by prefix and with channel info.

### Method
GET

### Endpoint
/apps/{appId}/channels

### Parameters
#### Path Parameters
- **appId** (string) - Required - The application ID.

#### Query Parameters
- **filter_by_prefix** (string) - Optional - Filter channels by prefix.
- **info** (string) - Optional - Request channel info.

### Response
#### Success Response (200)
- **channels** (object) - Object mapping channel names to info objects.

#### Response Example
{
  "channels": {
    "channel-name": {}
  }
}
```

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

### GET /apps/{appId}/channels/{channel}

Source: https://github.com/laravel/reverb/blob/main/_autodocs/endpoints.md

Retrieve information about a specific channel. Requires HMAC signature authentication.

```APIDOC
## GET /apps/{appId}/channels/{channel}

### Description
Retrieve information about a specific channel. Requires HMAC signature authentication.

### Method
GET

### Endpoint
/apps/{appId}/channels/{channel}

### Parameters
#### Path Parameters
- **appId** (string) - Required - The application ID.
- **channel** (string) - Required - The channel name.

#### Query Parameters
- **auth_key** (string) - Required - Application key.
- **auth_timestamp** (integer) - Required - Unix seconds; must be within 600 seconds of server time.
- **auth_version** (string) - Required - Version string.
- **auth_signature** (string) - Required - Hex HMAC-SHA256 signature.

### Response
#### Success Response (200)
Channel information.

#### Error Response (401)
Authentication signature invalid.

```

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

### GET /up

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/http-controllers.md

Health check endpoint that returns a simple health status. No authentication or app ID is required.

```APIDOC
## GET /up

### Description
Health check endpoint that returns a simple health status. No authentication or app ID is required.

### Method
GET

### Endpoint
/up

### Response
#### Success Response (200)
- **health** (string) - Always "OK" when the service is healthy.

#### Response Example
{
  "health": "OK"
}
```

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

### GET /apps/{appId}/channels/{channel}/users

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/http-controllers.md

Retrieves the list of user IDs subscribed to a presence channel.

```APIDOC
## GET /apps/{appId}/channels/{channel}/users

### Description
Retrieves the list of user IDs for a presence channel.

### Method
GET

### Endpoint
/apps/{appId}/channels/{channel}/users

### Parameters
#### Path Parameters
- **appId** (string) - Required - The application ID.
- **channel** (string) - Required - The channel name.

### Response
#### Success Response (200)
Returns a JSON object with a `users` array containing user objects with `id` fields.

#### Response Example
```json
{"users": [{"id": "user_id"}]}
```

#### Error Responses
- **404** - Channel not found.
- **400** - Channel exists but is not a presence channel.
```

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

### GET /apps/{appId}/channels/{channel}/users

Source: https://github.com/laravel/reverb/blob/main/_autodocs/endpoints.md

Retrieve the list of users subscribed to a channel. Requires HMAC signature authentication.

```APIDOC
## GET /apps/{appId}/channels/{channel}/users

### Description
Retrieve the list of users subscribed to a channel. Requires HMAC signature authentication.

### Method
GET

### Endpoint
/apps/{appId}/channels/{channel}/users

### Parameters
#### Path Parameters
- **appId** (string) - Required - The application ID.
- **channel** (string) - Required - The channel name.

#### Query Parameters
- **auth_key** (string) - Required - Application key.
- **auth_timestamp** (integer) - Required - Unix seconds; must be within 600 seconds of server time.
- **auth_version** (string) - Required - Version string.
- **auth_signature** (string) - Required - Hex HMAC-SHA256 signature.

### Response
#### Success Response (200)
List of users.

#### Error Response (401)
Authentication signature invalid.

```

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

### Application getter method signatures

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/core.md

List of getter method signatures for the Application class. All getters return the constructor value unchanged. usesRateLimiting() returns true only when the 'enabled' key of the rateLimiting array is exactly true.

```php
public function id(): string
public function key(): string
public function secret(): string
public function allowedOrigins(): array       // array<int, string>
public function pingInterval(): int
public function activityTimeout(): int
public function maxConnections(): ?int
public function hasMaxConnectionLimit(): bool // maxConnections !== null
public function maxMessageSize(): int
public function acceptClientEventsFrom(): string
public function rateLimiting(): ?array
public function usesRateLimiting(): bool      // (rateLimiting['enabled'] ?? false) === true
public function options(): ?array
```

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

### RedisPubSubProvider constructor

Source: https://github.com/laravel/reverb/blob/main/_autodocs/api-reference/redis.md

Constructor for RedisPubSubProvider, which implements PubSubProvider. Accepts a RedisClientFactory, a message handler, a channel name, and an optional server configuration array.

```php
public function __construct(
    protected RedisClientFactory $clientFactory,
    protected PubSubIncomingMessageHandler $messageHandler,
    protected string $channel,
    protected array $server = []
)
```
Tokens:
Raw