diff --git a/broadcasting.md b/broadcasting.md index 0cde2837e2..bb86e5f324 100644 --- a/broadcasting.md +++ b/broadcasting.md @@ -36,6 +36,10 @@ - [Model Broadcasting](#model-broadcasting) - [Model Broadcasting Conventions](#model-broadcasting-conventions) - [Listening for Model Broadcasts](#listening-for-model-broadcasts) +- [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) @@ -1213,6 +1217,88 @@ 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.ts ** 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. + ## Client Events @@ -1253,4 +1339,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