diff --git a/reverb.md b/reverb.md index 58253194af..4a1ff68806 100644 --- a/reverb.md +++ b/reverb.md @@ -11,6 +11,9 @@ - [Debugging](#debugging) - [Restarting](#restarting) - [Monitoring](#monitoring) +- [Events](#events) + - [Dispatched Events](#dispatched-events) + - [Listening for Events](#listening-for-events) - [Running Reverb in Production](#production) - [Open Files](#open-files) - [Event Loop](#event-loop) @@ -192,6 +195,66 @@ Next, add the Pulse cards for each recorder to your [Pulse dashboard](/docs/{{ve Connection activity is recorded by polling for new updates on a periodic basis. To ensure this information is rendered correctly on the Pulse dashboard, you must run the `pulse:check` daemon on your Reverb server. If you are running Reverb in a [horizontally scaled](#scaling) configuration, you should only run this daemon on one of your servers. + +## Events + +Reverb dispatches internal events during the lifecycle of a connection and message handling. You may listen for these events using [Laravel Event Listener](/docs/{{version}}/events) to perform actions when connections are managed or messages are exchanged. + + +### Dispatched Events + +The following events are dispatched by Reverb: + +
+ +| Event Name | Class | Description | +| --- | --- | --- | +| ChannelCreated | [`Laravel\Reverb\Events\ChannelCreated`](https://github.com/laravel/reverb/blob/main/src/Events/ChannelCreated.php) | Dispatched when a channel is created. This typically occurs when the first connection subscribes to a specific channel. The event receives the `Laravel\Reverb\Protocols\Pusher\Channel` instance. | +| ChannelRemoved | [`Laravel\Reverb\Events\ChannelRemoved`](https://github.com/laravel/reverb/blob/main/src/Events/ChannelRemoved.php) | Dispatched when a channel is removed. This typically occurs when the last connection unsubscribes from a channel. The event receives the `Laravel\Reverb\Protocols\Pusher\Channel` instance. | +| ConnectionPruned | [`Laravel\Reverb\Events\ConnectionPruned`](https://github.com/laravel/reverb/blob/main/src/Events/ConnectionPruned.php) | Dispatched when a stale connection is pruned by the server. The event receives the `Laravel\Reverb\Contracts\Connection` instance. | +| MessageReceived | [`Laravel\Reverb\Events\MessageReceived`](https://github.com/laravel/reverb/blob/main/src/Events/MessageReceived.php) | Dispatched when a message is received from a client connection. The event receives the `Laravel\Reverb\Contracts\Connection` instance and the raw string `$message`. | +| MessageSent | [`Laravel\Reverb\Events\MessageSent`](https://github.com/laravel/reverb/blob/main/src/Events/MessageSent.php) | Dispatched when a message is sent to a client connection. The event receives the `Laravel\Reverb\Contracts\Connection` instance and the raw string `$message`. | + +
+ + +### Listening for Events + +As these events are dispatched internally by Reverb, you cannot modify them directly. However, you can listen for them by defining a listener in your application. + +First, create a listener using the `make:listener` Artisan command: + +```shell +php artisan make:listener LogMessageReceived --event="\Laravel\Reverb\Events\MessageReceived" +``` + +Next, define the logic in your listener's `handle` method. You may access the connection and message data via the event's public properties: + +```php +message; + + // Access the connection details... + $socketId = $event->connection->id(); + } +} +``` + +Finally, ensure your listener is registered in your application's [AppServiceProvider](/docs/{{version}}/events#manually-registering-events) or automatically discovered if you are using event discovery. + ## Running Reverb in Production