From 59953e2c916c148587a998bda7339aa722453f09 Mon Sep 17 00:00:00 2001 From: Tony Lea Date: Wed, 26 Mar 2025 10:02:04 -0400 Subject: [PATCH 1/6] Adding updates to broadcasting to teach users how to use broadcasting in starter kits --- broadcasting.md | 143 ++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 126 insertions(+), 17 deletions(-) diff --git a/broadcasting.md b/broadcasting.md index 0cde2837e2..af1b21acb3 100644 --- a/broadcasting.md +++ b/broadcasting.md @@ -1,43 +1,62 @@ # Broadcasting -- [Introduction](#introduction) -- [Server Side Installation](#server-side-installation) +- [Broadcasting](#broadcasting) + - [Introduction](#introduction) + - [Supported Drivers](#supported-drivers) + - [Server Side Installation](#server-side-installation) - [Configuration](#configuration) + - [Installation](#installation) + - [Queue Configuration](#queue-configuration) - [Reverb](#reverb) - [Pusher Channels](#pusher-channels) - [Ably](#ably) -- [Client Side Installation](#client-side-installation) - - [Reverb](#client-reverb) - - [Pusher Channels](#client-pusher-channels) - - [Ably](#client-ably) -- [Concept Overview](#concept-overview) - - [Using an Example Application](#using-example-application) -- [Defining Broadcast Events](#defining-broadcast-events) + - [Client Side Installation](#client-side-installation) + - [Reverb](#reverb-1) + - [Pusher Channels](#pusher-channels-1) + - [Using an Existing Client Instance](#using-an-existing-client-instance) + - [Ably](#ably-1) + - [Concept Overview](#concept-overview) + - [Using an Example Application](#using-an-example-application) + - [The `ShouldBroadcast` Interface](#the-shouldbroadcast-interface) + - [Authorizing Channels](#authorizing-channels) + - [Listening for Event Broadcasts](#listening-for-event-broadcasts) + - [Defining Broadcast Events](#defining-broadcast-events) - [Broadcast Name](#broadcast-name) - [Broadcast Data](#broadcast-data) - [Broadcast Queue](#broadcast-queue) - [Broadcast Conditions](#broadcast-conditions) - - [Broadcasting and Database Transactions](#broadcasting-and-database-transactions) -- [Authorizing Channels](#authorizing-channels) + - [Broadcasting and Database Transactions](#broadcasting-and-database-transactions) + - [Authorizing Channels](#authorizing-channels-1) - [Defining Authorization Callbacks](#defining-authorization-callbacks) + - [Authorization Callback Model Binding](#authorization-callback-model-binding) + - [Authorization Callback Authentication](#authorization-callback-authentication) - [Defining Channel Classes](#defining-channel-classes) -- [Broadcasting Events](#broadcasting-events) + - [Broadcasting Events](#broadcasting-events) - [Only to Others](#only-to-others) + - [Configuration](#configuration-1) - [Customizing the Connection](#customizing-the-connection) - [Anonymous Events](#anonymous-events) -- [Receiving Broadcasts](#receiving-broadcasts) + - [Receiving Broadcasts](#receiving-broadcasts) - [Listening for Events](#listening-for-events) + - [Stop Listening for Events](#stop-listening-for-events) - [Leaving a Channel](#leaving-a-channel) - [Namespaces](#namespaces) -- [Presence Channels](#presence-channels) + - [Presence Channels](#presence-channels) - [Authorizing Presence Channels](#authorizing-presence-channels) - [Joining Presence Channels](#joining-presence-channels) - [Broadcasting to Presence Channels](#broadcasting-to-presence-channels) -- [Model Broadcasting](#model-broadcasting) + - [Model Broadcasting](#model-broadcasting) + - [Customizing Model Broadcasting Event Creation](#customizing-model-broadcasting-event-creation) - [Model Broadcasting Conventions](#model-broadcasting-conventions) + - [Channel Conventions](#channel-conventions) + - [Event Conventions](#event-conventions) - [Listening for Model Broadcasts](#listening-for-model-broadcasts) -- [Client Events](#client-events) -- [Notifications](#notifications) + - [Installation in Starter Kits](#installation-in-starter-kits) + - [Using the Hook/Composable](#using-the-hookcomposable) + - [Configuring Echo in Starter Kits](#configuring-echo-in-starter-kits) + - [Testing Broadcasting in Starter Kits](#testing-broadcasting-in-starter-kits) + - [Client Events](#client-events) + - [Notifications](#notifications) ## Introduction @@ -1213,6 +1232,96 @@ Echo.private(`App.Models.User.${this.user.id}`) }); ``` + +## Installation in Starter Kits + +Using broadcasting in your React or Vue starter kit is incredibly simple. When you run the `install:broadcasting` command, a [hook](https://react.dev/reference/react/hooks) or [composable](https://vuejs.org/guide/reusability/composables) will automatically be published to your `resources/js` folder. From there, you can immediately start listening to events. + +> [!NOTE] +> Using the Livewire starter kit? Livewire offers seamless integration with WebSockets. [Learn more here](https://livewire.laravel.com/docs/events#real-time-events-using-laravel-echo). + + +### Using the Hook/Composable + +To begin listening for events, first, import the hook or composable into any component or page: + +```jsx +// For React +import { useEcho } from '@/hooks/use-echo'; + +// For Vue +import { useEcho } from '@/composables/useEcho'; +``` + +Then, use the `useEcho` hook or composable to listen for events: + +```jsx +useEcho('test-channel', 'test.event', (payload) => { console.log(payload) }, [], 'public'); +``` + + +### Configuring Echo in Starter Kits + +The `install:broadcasting` command automatically injects the necessary Echo configuration into your **app.tsx** or **app.vue** file: + +```ts +// For React +import { configureEcho } from './hooks/use-echo'; +// For Vue +import { configureEcho } from './composables/useEcho'; + +configureEcho({ + broadcaster: 'reverb', + key: import.meta.env.VITE_REVERB_APP_KEY, + wsHost: import.meta.env.VITE_REVERB_HOST, + wsPort: import.meta.env.VITE_REVERB_PORT ?? 80, + wssPort: import.meta.env.VITE_REVERB_PORT ?? 443, + forceTLS: (import.meta.env.VITE_REVERB_SCHEME ?? 'https') === 'https', + enabledTransports: ['ws', 'wss'], +}); +``` + +You can modify this configuration to use `reverb`, `pusher`, `ably`, or any other WebSocket service of your choice. + + +### Testing Broadcasting in Starter Kits + +You can broadcast a message using a Laravel Event or an anonymous event. For simplicity, we'll use an anonymous event in this example. + +If you've implemented one of the listener examples above and are listening on the `test-channel` for a `test.event`, you can trigger a broadcast by creating a simple GET route in your `routes/web.php` file like so: + +```php +use Illuminate\Support\Facades\Broadcast; + +Route::get('test-channel', function () { + Broadcast::on('test-channel') + ->as('test.event') + ->with(['message' => 'Hello World!']) + ->send(); +}); +``` + +Next, navigate to a page listening on the `test-channel`. Open your browser's developer tools and go to the **Network** tab. You should see a WebSocket connection to the server. Click on that request to view the incoming messages. + +Then, open a new browser tab and visit the `/test-channel` route. You should now see a new message in the WebSocket logs with the following payload: + +```json +{ + "event": "test.event", + "data": "{\"message\":\"Hello World!\"}", + "channel": "test-channel" +} +``` + +You can decode this payload to access the event data. And just like that, you've set up a real-time socket connection where the server can send messages directly to the client. + +> It may be easier to + + +You may use a Laravel Event to broadcast a message to a channel or you can use an Anonymous event +Before using this hook/composable, echo needs to be configured, like so: +When you install broadcasting via the `install:broadcasting` command, a [hook](https://react.dev/reference/react/hooks) or [composable](https://vuejs.org/guide/reusability/composables) will automatically be published to your `resources/js` folder, and you can immediately start listening for events. + ## Client Events From 1eaf971c1f26af7df66b5d8cce21fd7a13957d9c Mon Sep 17 00:00:00 2001 From: Tony Lea Date: Wed, 26 Mar 2025 10:08:51 -0400 Subject: [PATCH 2/6] Adding updates to formatting --- broadcasting.md | 81 ++++++++++++++++++++++++++++--------------------- 1 file changed, 46 insertions(+), 35 deletions(-) diff --git a/broadcasting.md b/broadcasting.md index af1b21acb3..c6835f703c 100644 --- a/broadcasting.md +++ b/broadcasting.md @@ -1,62 +1,47 @@ # Broadcasting -- [Broadcasting](#broadcasting) - - [Introduction](#introduction) - - [Supported Drivers](#supported-drivers) - - [Server Side Installation](#server-side-installation) +- [Introduction](#introduction) +- [Server Side Installation](#server-side-installation) - [Configuration](#configuration) - - [Installation](#installation) - - [Queue Configuration](#queue-configuration) - [Reverb](#reverb) - [Pusher Channels](#pusher-channels) - [Ably](#ably) - - [Client Side Installation](#client-side-installation) - - [Reverb](#reverb-1) - - [Pusher Channels](#pusher-channels-1) - - [Using an Existing Client Instance](#using-an-existing-client-instance) - - [Ably](#ably-1) - - [Concept Overview](#concept-overview) - - [Using an Example Application](#using-an-example-application) - - [The `ShouldBroadcast` Interface](#the-shouldbroadcast-interface) - - [Authorizing Channels](#authorizing-channels) - - [Listening for Event Broadcasts](#listening-for-event-broadcasts) - - [Defining Broadcast Events](#defining-broadcast-events) +- [Client Side Installation](#client-side-installation) + - [Reverb](#client-reverb) + - [Pusher Channels](#client-pusher-channels) + - [Ably](#client-ably) +- [Concept Overview](#concept-overview) + - [Using an Example Application](#using-example-application) +- [Defining Broadcast Events](#defining-broadcast-events) - [Broadcast Name](#broadcast-name) - [Broadcast Data](#broadcast-data) - [Broadcast Queue](#broadcast-queue) - [Broadcast Conditions](#broadcast-conditions) - - [Broadcasting and Database Transactions](#broadcasting-and-database-transactions) - - [Authorizing Channels](#authorizing-channels-1) + - [Broadcasting and Database Transactions](#broadcasting-and-database-transactions) +- [Authorizing Channels](#authorizing-channels) - [Defining Authorization Callbacks](#defining-authorization-callbacks) - - [Authorization Callback Model Binding](#authorization-callback-model-binding) - - [Authorization Callback Authentication](#authorization-callback-authentication) - [Defining Channel Classes](#defining-channel-classes) - - [Broadcasting Events](#broadcasting-events) +- [Broadcasting Events](#broadcasting-events) - [Only to Others](#only-to-others) - - [Configuration](#configuration-1) - [Customizing the Connection](#customizing-the-connection) - [Anonymous Events](#anonymous-events) - - [Receiving Broadcasts](#receiving-broadcasts) +- [Receiving Broadcasts](#receiving-broadcasts) - [Listening for Events](#listening-for-events) - - [Stop Listening for Events](#stop-listening-for-events) - [Leaving a Channel](#leaving-a-channel) - [Namespaces](#namespaces) - - [Presence Channels](#presence-channels) +- [Presence Channels](#presence-channels) - [Authorizing Presence Channels](#authorizing-presence-channels) - [Joining Presence Channels](#joining-presence-channels) - [Broadcasting to Presence Channels](#broadcasting-to-presence-channels) - - [Model Broadcasting](#model-broadcasting) - - [Customizing Model Broadcasting Event Creation](#customizing-model-broadcasting-event-creation) +- [Model Broadcasting](#model-broadcasting) - [Model Broadcasting Conventions](#model-broadcasting-conventions) - - [Channel Conventions](#channel-conventions) - - [Event Conventions](#event-conventions) - [Listening for Model Broadcasts](#listening-for-model-broadcasts) - - [Installation in Starter Kits](#installation-in-starter-kits) - - [Using the Hook/Composable](#using-the-hookcomposable) +- [Installation in Starter Kits](#installation-in-starter-kits) + - [Using the Hook/Composable](#using-the-hook-composable) - [Configuring Echo in Starter Kits](#configuring-echo-in-starter-kits) - [Testing Broadcasting in Starter Kits](#testing-broadcasting-in-starter-kits) - - [Client Events](#client-events) - - [Notifications](#notifications) +- [Client Events](#client-events) +- [Notifications](#notifications) ## Introduction @@ -1232,6 +1217,32 @@ Echo.private(`App.Models.User.${this.user.id}`) }); ``` + +## Client Events + +> [!NOTE] +> When using [Pusher Channels](https://pusher.com/channels), you must enable the "Client Events" option in the "App Settings" section of your [application dashboard](https://dashboard.pusher.com/) in order to send client events. + +Sometimes you may wish to broadcast an event to other connected clients without hitting your Laravel application at all. This can be particularly useful for things like "typing" notifications, where you want to alert users of your application that another user is typing a message on a given screen. + +To broadcast client events, you may use Echo's `whisper` method: + +```js +Echo.private(`chat.${roomId}`) + .whisper('typing', { + name: this.user.name + }); +``` + +To listen for client events, you may use the `listenForWhisper` method: + +```js +Echo.private(`chat.${roomId}`) + .listenForWhisper('typing', (e) => { + console.log(e.name); + }); +``` + ## Installation in Starter Kits @@ -1362,4 +1373,4 @@ Echo.private(`App.Models.User.${userId}`) }); ``` -In this example, all notifications sent to `App\Models\User` instances via the `broadcast` channel would be received by the callback. A channel authorization callback for the `App.Models.User.{id}` channel is included in your application's `routes/channels.php` file. +In this example, all notifications sent to `App\Models\User` instances via the `broadcast` channel would be received by the callback. A channel authorization callback for the `App.Models.User.{id}` channel is included in your application's `routes/channels.php` file. \ No newline at end of file From ec45e3bd3d26c5d61b4e4e884cffa362004fdcb1 Mon Sep 17 00:00:00 2001 From: Tony Lea Date: Wed, 26 Mar 2025 10:12:58 -0400 Subject: [PATCH 3/6] Adding updates to formatting --- broadcasting.md | 52 ------------------------------------------------- 1 file changed, 52 deletions(-) diff --git a/broadcasting.md b/broadcasting.md index c6835f703c..6e3d34885b 100644 --- a/broadcasting.md +++ b/broadcasting.md @@ -1217,45 +1217,14 @@ Echo.private(`App.Models.User.${this.user.id}`) }); ``` - -## Client Events - -> [!NOTE] -> When using [Pusher Channels](https://pusher.com/channels), you must enable the "Client Events" option in the "App Settings" section of your [application dashboard](https://dashboard.pusher.com/) in order to send client events. - -Sometimes you may wish to broadcast an event to other connected clients without hitting your Laravel application at all. This can be particularly useful for things like "typing" notifications, where you want to alert users of your application that another user is typing a message on a given screen. - -To broadcast client events, you may use Echo's `whisper` method: - -```js -Echo.private(`chat.${roomId}`) - .whisper('typing', { - name: this.user.name - }); -``` - -To listen for client events, you may use the `listenForWhisper` method: - -```js -Echo.private(`chat.${roomId}`) - .listenForWhisper('typing', (e) => { - console.log(e.name); - }); -``` - ## Installation in Starter Kits - Using broadcasting in your React or Vue starter kit is incredibly simple. When you run the `install:broadcasting` command, a [hook](https://react.dev/reference/react/hooks) or [composable](https://vuejs.org/guide/reusability/composables) will automatically be published to your `resources/js` folder. From there, you can immediately start listening to events. - > [!NOTE] > Using the Livewire starter kit? Livewire offers seamless integration with WebSockets. [Learn more here](https://livewire.laravel.com/docs/events#real-time-events-using-laravel-echo). - ### Using the Hook/Composable - To begin listening for events, first, import the hook or composable into any component or page: - ```jsx // For React import { useEcho } from '@/hooks/use-echo'; @@ -1263,18 +1232,13 @@ import { useEcho } from '@/hooks/use-echo'; // For Vue import { useEcho } from '@/composables/useEcho'; ``` - Then, use the `useEcho` hook or composable to listen for events: - ```jsx useEcho('test-channel', 'test.event', (payload) => { console.log(payload) }, [], 'public'); ``` - ### Configuring Echo in Starter Kits - The `install:broadcasting` command automatically injects the necessary Echo configuration into your **app.tsx** or **app.vue** file: - ```ts // For React import { configureEcho } from './hooks/use-echo'; @@ -1291,16 +1255,11 @@ configureEcho({ enabledTransports: ['ws', 'wss'], }); ``` - You can modify this configuration to use `reverb`, `pusher`, `ably`, or any other WebSocket service of your choice. - ### Testing Broadcasting in Starter Kits - You can broadcast a message using a Laravel Event or an anonymous event. For simplicity, we'll use an anonymous event in this example. - If you've implemented one of the listener examples above and are listening on the `test-channel` for a `test.event`, you can trigger a broadcast by creating a simple GET route in your `routes/web.php` file like so: - ```php use Illuminate\Support\Facades\Broadcast; @@ -1311,11 +1270,8 @@ Route::get('test-channel', function () { ->send(); }); ``` - Next, navigate to a page listening on the `test-channel`. Open your browser's developer tools and go to the **Network** tab. You should see a WebSocket connection to the server. Click on that request to view the incoming messages. - Then, open a new browser tab and visit the `/test-channel` route. You should now see a new message in the WebSocket logs with the following payload: - ```json { "event": "test.event", @@ -1323,16 +1279,8 @@ Then, open a new browser tab and visit the `/test-channel` route. You should now "channel": "test-channel" } ``` - You can decode this payload to access the event data. And just like that, you've set up a real-time socket connection where the server can send messages directly to the client. -> It may be easier to - - -You may use a Laravel Event to broadcast a message to a channel or you can use an Anonymous event -Before using this hook/composable, echo needs to be configured, like so: -When you install broadcasting via the `install:broadcasting` command, a [hook](https://react.dev/reference/react/hooks) or [composable](https://vuejs.org/guide/reusability/composables) will automatically be published to your `resources/js` folder, and you can immediately start listening for events. - ## Client Events From c6eaa133c578392269ce0312a404dcfa8fc239ea Mon Sep 17 00:00:00 2001 From: Tony Lea Date: Fri, 28 Mar 2025 16:05:26 -0400 Subject: [PATCH 4/6] fixing spacing --- broadcasting.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/broadcasting.md b/broadcasting.md index 6e3d34885b..6d08f9cbb2 100644 --- a/broadcasting.md +++ b/broadcasting.md @@ -1219,12 +1219,17 @@ Echo.private(`App.Models.User.${this.user.id}`) ## Installation in Starter Kits + Using broadcasting in your React or Vue starter kit is incredibly simple. When you run the `install:broadcasting` command, a [hook](https://react.dev/reference/react/hooks) or [composable](https://vuejs.org/guide/reusability/composables) will automatically be published to your `resources/js` folder. From there, you can immediately start listening to events. + > [!NOTE] > Using the Livewire starter kit? Livewire offers seamless integration with WebSockets. [Learn more here](https://livewire.laravel.com/docs/events#real-time-events-using-laravel-echo). + ### Using the Hook/Composable + To begin listening for events, first, import the hook or composable into any component or page: + ```jsx // For React import { useEcho } from '@/hooks/use-echo'; @@ -1232,13 +1237,17 @@ import { useEcho } from '@/hooks/use-echo'; // For Vue import { useEcho } from '@/composables/useEcho'; ``` + Then, use the `useEcho` hook or composable to listen for events: + ```jsx useEcho('test-channel', 'test.event', (payload) => { console.log(payload) }, [], 'public'); ``` ### Configuring Echo in Starter Kits + The `install:broadcasting` command automatically injects the necessary Echo configuration into your **app.tsx** or **app.vue** file: + ```ts // For React import { configureEcho } from './hooks/use-echo'; @@ -1255,11 +1264,15 @@ configureEcho({ enabledTransports: ['ws', 'wss'], }); ``` + You can modify this configuration to use `reverb`, `pusher`, `ably`, or any other WebSocket service of your choice. + ### Testing Broadcasting in Starter Kits + You can broadcast a message using a Laravel Event or an anonymous event. For simplicity, we'll use an anonymous event in this example. If you've implemented one of the listener examples above and are listening on the `test-channel` for a `test.event`, you can trigger a broadcast by creating a simple GET route in your `routes/web.php` file like so: + ```php use Illuminate\Support\Facades\Broadcast; @@ -1270,8 +1283,11 @@ Route::get('test-channel', function () { ->send(); }); ``` + Next, navigate to a page listening on the `test-channel`. Open your browser's developer tools and go to the **Network** tab. You should see a WebSocket connection to the server. Click on that request to view the incoming messages. + Then, open a new browser tab and visit the `/test-channel` route. You should now see a new message in the WebSocket logs with the following payload: + ```json { "event": "test.event", @@ -1279,6 +1295,7 @@ Then, open a new browser tab and visit the `/test-channel` route. You should now "channel": "test-channel" } ``` + You can decode this payload to access the event data. And just like that, you've set up a real-time socket connection where the server can send messages directly to the client. From efeda054cce742df8049785128ef8d505f2722b8 Mon Sep 17 00:00:00 2001 From: Tony Lea Date: Fri, 28 Mar 2025 16:07:47 -0400 Subject: [PATCH 5/6] updating correct filename --- broadcasting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/broadcasting.md b/broadcasting.md index 6d08f9cbb2..fcb2ca93e1 100644 --- a/broadcasting.md +++ b/broadcasting.md @@ -1246,7 +1246,7 @@ useEcho('test-channel', 'test.event', (payload) => { console.log(payload) }, [], ### Configuring Echo in Starter Kits -The `install:broadcasting` command automatically injects the necessary Echo configuration into your **app.tsx** or **app.vue** file: +The `install:broadcasting` command automatically injects the necessary Echo configuration into your **app.tsx** or **app.ts ** file: ```ts // For React From 23a0c49cde008ebbb84290c833961c323dca79ac Mon Sep 17 00:00:00 2001 From: Tony Lea Date: Fri, 28 Mar 2025 16:08:49 -0400 Subject: [PATCH 6/6] fixing additional space --- broadcasting.md | 1 + 1 file changed, 1 insertion(+) diff --git a/broadcasting.md b/broadcasting.md index fcb2ca93e1..bb86e5f324 100644 --- a/broadcasting.md +++ b/broadcasting.md @@ -1271,6 +1271,7 @@ You can modify this configuration to use `reverb`, `pusher`, `ably`, or any othe ### Testing Broadcasting in Starter Kits You can broadcast a message using a Laravel Event or an anonymous event. For simplicity, we'll use an anonymous event in this example. + If you've implemented one of the listener examples above and are listening on the `test-channel` for a `test.event`, you can trigger a broadcast by creating a simple GET route in your `routes/web.php` file like so: ```php