Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
slavarazum authored Jun 9, 2023
1 parent 12a34a0 commit 22c32e3
Showing 1 changed file with 20 additions and 101 deletions.
121 changes: 20 additions & 101 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,120 +36,39 @@

# Introduction

Leverage Laravel's [broadcasting system](https://laravel.com/docs/master/broadcasting) for seamless communication between server and client using
🗼 [**Server-sent Events**](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events).
This package is compatible with [Laravel Echo](https://github.com/laravel/echo).🐤
Unlock the power of Laravel's [broadcasting system](https://laravel.com/docs/master/broadcasting)
with **Wave**. Imagine that real-time server broadcasting is possible over native HTTP without any WebSockets setup.

Enjoy a live [demo stream of tweets](https://wave.qruto.dev) 🐤.
Meet the [**Server-sent Events**](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) 🗼 Works seamlessly with Laravel's default `redis` broadcasting driver and supports [Laravel Echo](https://github.com/laravel/echo).

> Server-Sent Events (**SSE**) is specially tuned for real-time server-to-client communication.
Experience it live with our [demo streaming tweets](https://wave.qruto.dev) 🐤.

## Support

I have spent a lot of effort playing with SSE, Laravel broadcasting system and Redis to prepare **Laravel Wave** and make it available for everyone. Since of February 24, unfortunately I haven't any commercial work, permanent living place or the ability to plan anything for the long term. However, I have a greater desire to continue creating useful solutions for people around the world. It makes me feel better these days.
In light of recent events in Ukraine, my life has taken an unexpected turn.
Since February 24th, I've lost my commercial work, my permanent residence,
and my ability to plan for the future.

During these challenging times, I derive strength and purpose from creating
open source projects, such as Wave.

[![support me](https://raw.githubusercontent.com/slavarazum/slavarazum/main/support-banner.png)](https://github.com/sponsors/qruto)

[GitHub Sponsorships profile](https://github.com/sponsors/qruto) is ready! There you can find current work, future plans, goals and dreams... Your stars make me happier each day ✨ Sponsorship will enable us to live more peacefully and continue to work on useful solutions for you.
I welcome you to visit my [GitHub Sponsorships profile](https://github.com/sponsors/qruto).
There, you can discover more about my current work, future ambitions, and aspirations.
Every ⭐ you give brings joy to my day, and your sponsorship can make
a profound difference in my ability to continue creating.

I would be very grateful for mentions or just a sincere "thank you".
I'm truly grateful for your support, whether it's a shout-out or a heartfelt "thank you".

💳 [Sponsoring directly to savings jar](https://send.monobank.ua/jar/3eG4Vafvzq) with **card** or **Apple Pay**/**Google Pay**.
💳 [Help directly](https://revolut.me/slavarazum).

## Documentation

Refer to the [Main Readme](https://github.com/qruto/laravel-wave#introduction)
for comprehensive documentation and Laravel's Broadcasting [guidelines](https://laravel.com/docs/9.x/broadcasting).

## Usage

### 1. With Laravel Echo

Import `WaveConnector` and set it as Echo's broadcaster:

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

import { WaveConnector } from 'laravel-wave';

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

In a fresh Laravel application, replace the Echo connection configuration in **resources/js/bootstrap.js** with the snippet above.
Now, you can use Echo as normal.

<details>
<summary>Show diff</summary>

```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 });
```

</details>

📞 [Receiving Broadcasts](https://laravel.com/docs/9.x/broadcasting#receiving-broadcasts)

### 2. Live Eloquent Models

With native conventions of [Model Events Broadcasting](https://laravel.com/docs/8.x/broadcasting#model-broadcasting)
and [Broadcast Notifications](https://laravel.com/docs/8.x/notifications#broadcast-notifications)
use Wave models to listen for predefined events.

```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));
```

Pass the model name and key to `model` to start listening.
By default, Wave uses `App.Models` as the namespace prefix, but you can override it:

```javascript
window.Wave = new Wave({ namespace: 'App.Path.Models' });
```

### Configuration Options

These options can be passed to the `Wave` or `Echo` instance:

| Name | Type | Default | Description |
|---------------|--------------------------------------------------------------------------------|-------------------------|--------------------------------------------------------------------------------|
| endpoint | _string_ | `/wave` | Primary SSE connection route. |
| namespace | _string_ | `App.Events` | Namespace of events to listen for. |
| auth.headers | _object_ | `{}` | Additional authentication headers. |
| authEndpoint | _string?_ | `/broadcasting/auth` | Authentication endpoint. |
| csrfToken | _string?_ | `undefined` or `string` | CSRF token, defaults from `XSRF-TOKEN` cookie. |
| bearerToken | _string?_ | `undefined` | Bearer tokenfor authentication. |
| request | _[Request](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request)?_ | `undefined` | Custom settings for connection and authentication requests. |
| pauseInactive | _boolean_ | `false` | If `true`, closes connection when the page is hidden and reopens when visible. |

[Main Readme](https://github.com/qruto/laravel-wave#introduction) – find full documentation here.
for comprehensive documentation and Laravel's Broadcasting [guidelines](https://laravel.com/docs/master/broadcasting).

## Changelog

Expand Down

0 comments on commit 22c32e3

Please sign in to comment.