Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ably/laravel-broadcaster
Official Laravel Ably Broadcaster
https://github.com/ably/laravel-broadcaster
ably broadcasting events laravel livewire php realtime sdk
Last synced: 3 days ago
JSON representation
Official Laravel Ably Broadcaster
- Host: GitHub
- URL: https://github.com/ably/laravel-broadcaster
- Owner: ably
- License: apache-2.0
- Created: 2022-09-26T12:23:04.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-03-14T10:57:41.000Z (9 months ago)
- Last Synced: 2024-03-14T19:59:50.528Z (9 months ago)
- Topics: ably, broadcasting, events, laravel, livewire, php, realtime, sdk
- Language: PHP
- Homepage: https://laravel.com/docs/broadcasting
- Size: 95.7 KB
- Stars: 36
- Watchers: 18
- Forks: 5
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Ably Broadcaster for Laravel
[](https://packagist.org/packages/ably/laravel-broadcaster)
[](https://packagist.org/packages/ably/laravel-broadcaster)
[](https://packagist.org/packages/ably/laravel-broadcaster)
_[Ably](https://ably.com) is the platform that powers synchronized digital experiences in realtime. Whether attending an event in a virtual venue, receiving realtime financial information, or monitoring live car performance data – consumers simply expect realtime digital experiences as standard. Ably provides a suite of APIs to build, extend, and deliver powerful digital experiences in realtime for more than 250 million devices across 80 countries each month. Organizations like Bloomberg, HubSpot, Verizon, and Hopin depend on Ably’s platform to offload the growing complexity of business-critical realtime data synchronization at global scale. For more information, see the [Ably documentation](https://ably.com/docs)._
This implements ably broadcaster as a independent service provider library for [Laravel](https://laravel.com/) using [ably-php](https://github.com/ably/ably-php). This library works with the [ably-js](https://github.com/ably/ably-js) based [ably-laravel-echo](https://github.com/ably-forks/echo) client framework with enhanced features. This project is the successor to the [pusher-client based ably broadcaster](https://laravel.com/docs/9.x/broadcasting#client-ably).
## Features
- Native ably-js support.
- Low latency for client-events.
- Update channel permissions for each user.
- Update token expiry.
- Disable public channels.
- Fully compatible with pusher/pusher-compatible broadcasters, see [migrating section](#migrating-from-pusherpusher-compatible-broadcasters).
## Bug Fixes
- Fixes [broadcasting events to others](https://faqs.ably.com/why-isnt-the-broadcast-only-to-others-functionality-working-in-laravel-with-the-ably-broadcaster).
- Fixes intermittent presence leave issue for channel members.
## Requirements
1. PHP version >= 7.2.0
2. Laravel version >= 6.0.0
## Installation
You can install the package via composer
```
composer require ably/laravel-broadcaster
```
## Setup
1. Update `.env` file, set `BROADCAST_CONNECTION` as `ably` and specify `ABLY_KEY`.
```dotenv
BROADCAST_CONNECTION=ably # For laravel <= 10, set `BROADCAST_DRIVER` instead
ABLY_KEY=ROOT_API_KEY_COPIED_FROM_ABLY_WEB_DASHBOARD
```
> **Warning** - Do not expose **ABLY_KEY** to client code.
2. If using laravel 10 or older, uncomment/set [**BroadcastServiceProvider** in config/app.php](https://github.com/ably-labs/laravel-broadcast-app/blob/3ae9b9b97e05c1394bf128ae4dd905e245c7db71/config/app.php#L174)
App\Providers\AuthServiceProvider::class,
App\Providers\BroadcastServiceProvider::class,
App\Providers\EventServiceProvider::class,
4. If running Laravel 8 or older, edit `config/broadcasting.php`, add `ably` section to the `connections` array
```php
'ably' => [
'driver' => 'ably',
'key' => env('ABLY_KEY')
],
```
- For more information, refer to the [server-side broadcasting configuration documentation](https://laravel.com/docs/broadcasting#configuration).
Finally, you are ready to install and configure [Ably Laravel Echo](https://github.com/ably-forks/echo/), which will receive the broadcast events on the client-side.
## Using Laravel Echo on client-side
[Ably Laravel Echo](https://github.com/ably-forks/echo/) is a JavaScript library that makes it painless to subscribe to channels and listen for events broadcast by your server-side broadcasting driver. Ably is maintaining a fork of the official laravel-echo module which allows you to use the official [ably-js SDK](https://github.com/ably/ably-js). In this example, we will also install the official ably package:
```
npm install @ably/laravel-echo [email protected]
```
Once Echo is installed, you are ready to create a fresh Echo instance in your applications JavaScript. A great place to do this is at the bottom of the `resources/js/bootstrap.js` file that is included with the Laravel framework. By default, an example Echo configuration is already included in this file; however, the default configuration in the `bootstrap.js` file is intended for Pusher. You may copy the configuration below to transition your configuration to Ably.
```js
import Echo from '@ably/laravel-echo';
import * as Ably from 'ably';
window.Ably = Ably;
window.Echo = new Echo({
broadcaster: 'ably',
});
window.Echo.connector.ably.connection.on(stateChange => {
if (stateChange.current === 'connected') {
console.log('connected to ably server');
}
});
```
Please take a look at the [**Ably Laravel Echo Docs**](https://github.com/ably-forks/laravel-echo#readme) for more information related to configuring ably-specific client options and implementing additional features.
Once you have uncommented and adjusted the Echo configuration according to your needs, you may compile your application's assets:
```shell
npm run dev
```
## Configure advanced features
**1. Modify private/presence channel capability. Default: Full capability**
- Channel access control rights are granted for each individual user separately using `ably-capability`. It defines list of access claims as per [Channel Capabilities](https://ably.com/docs/core-features/authentication#capability-operations).
```php
// file - routes/channels.php
// User authentication is allowed for private/presence channel returning truthy values and denied for falsy values.
// for private channel
Broadcast::channel('channel1', function ($user) {
return ['ably-capability' => ["subscribe", "history"]];
});
// for presence channel
Broadcast::channel('channel2', function ($user) {
return ['id' => $user->id, 'name' => $user->name, 'ably-capability' => ["subscribe", "presence"]];
});
```
**2. Disable public channels. Default: false**
- Set `ABLY_DISABLE_PUBLIC_CHANNELS` as **true** in **.env** file.
```dotenv
ABLY_DISABLE_PUBLIC_CHANNELS=true
```
- Update ably section under `config/broadcasting.php` with
```php
'ably' => [
'driver' => 'ably',
'key' => env('ABLY_KEY'),
'disable_public_channels' => env('ABLY_DISABLE_PUBLIC_CHANNELS', false)
],
```
**3. Update token expiry. Default: 3600 seconds (1 hr)**
- Set `ABLY_TOKEN_EXPIRY` in **.env** file.
```dotenv
ABLY_TOKEN_EXPIRY=21600
```
- Update ably section under `config/broadcasting.php` with
```php
'ably' => [
'driver' => 'ably',
'key' => env('ABLY_KEY'),
'token_expiry' => env('ABLY_TOKEN_EXPIRY', 3600)
],
```
**4. Use internet time for issued token expiry. Default: false**
- If this option is enabled, internet time in UTC format is fetched from the Ably service and cached every 6 hrs.
- This option is useful when using laravel-broadcaster on a server where, for some reason, the server clock cannot be kept synchronized through normal means.
- Set `ABLY_SYNC_SERVER_TIME` as **true** in **.env** file.
```dotenv
ABLY_SYNC_SERVER_TIME=true
```
- Update ably section under `config/broadcasting.php` with
```php
'ably' => [
'driver' => 'ably',
'key' => env('ABLY_KEY'),
'sync_server_time' => env('ABLY_SYNC_SERVER_TIME', false)
],
```
## Migrating from pusher/pusher-compatible broadcasters
The Ably Laravel broadcaster is designed to be compatible with all Laravel broadcasting providers, such as [Pusher](https://laravel.com/docs/9.x/broadcasting#pusher-channels), [Ably with the Pusher adapter](https://laravel.com/docs/9.x/broadcasting#ably), and all [Pusher compatible open source broadcasters](https://laravel.com/docs/9.x/broadcasting#open-source-alternatives). Follow the below steps to migrate from other broadcasters.
**1. Leaving a channel**
To leave channel on the client side, use [Ably Channel Namespaces](https://ably.com/docs/general/channel-rules-namespaces) conventions, instead of [Pusher Channel Conventions](https://pusher.com/docs/channels/using_channels/channels/#channel-types).
```js
// public channel
Echo.channel('channel1'); // subscribe to a public channel
// use this
Echo.leaveChannel("public:channel1"); // ably convention for leaving public channel
// instead of
Echo.leaveChannel("channel1"); // pusher convention for leaving public channel
// private channel
Echo.private('channel2'); // subscribe to a private channel
// use this
Echo.leaveChannel("private:channel2"); // ably convention for leaving private channel
// instead of
Echo.leaveChannel("private-channel2"); // pusher convention for leaving private channel
// presence channel
Echo.join('channel3'); // subscribe to a presence channel
// use this
Echo.leaveChannel("presence:channel3"); // ably convention for leaving presence channel
// instead of
Echo.leaveChannel("presence-channel3"); // pusher convention for leaving presence channel
```
**2. Error handling**
- Please note that the [Ably laravel-echo client](https://github.com/ably-forks/laravel-echo) emits [Ably specific error codes](https://github.com/ably/ably-common/blob/main/protocol/errors.json) instead of [Pusher error codes](https://pusher.com/docs/channels/library_auth_reference/pusher-websockets-protocol/#error-codes).
- Ably emitted errors are descriptive and easy to understand, so it's more effective to take a corrective action.
- Ably errors are provided as an [ErrorInfo object](https://ably.com/docs/api/realtime-sdk/types#error-info) with full error context.
- If you are interacting with pusher errors in your project, be sure to update your code accordingly.
i.e. update from [pusher error codes](https://pusher.com/docs/channels/library_auth_reference/pusher-websockets-protocol/#error-codes) to [ably error codes](https://github.com/ably/ably-common/blob/main/protocol/errors.json).
```js
channel.error(error => {
if (error && error.code === 40142) { // ably token expired
console.error(error);
// take corrective action on UI
}
})
```
**Note :**
- In the `Echo.join().here(members => {})` implementation, members are updated every time a client **joins, updates or leaves** the channel, whereas when using Pusher this is only called once for first client entering the channel.
- Ably behaviour follows the standard Echo [PresenceChannel Interface `here` Method](https://github.com/laravel/echo/blob/master/src/channel/presence-channel.ts#L10).
## Addtional Documentation
- Current README covers basic ably broadcaster+echo configuration for setting up laravel app and getting it running.
- Please take a look at [Laravel Broadcasting Doc](https://laravel.com/docs/broadcasting) for more information on broadcasting and receiving events.
## Example
- We have created a demo web-chat app using Ably Broadcaster+Echo based on laravel.
- Visit https://github.com/ably-labs/laravel-broadcast-app for detailed information.
## Testing
- To run tests use
``` bash
composer test
```
- Integration tested using [ably sandbox](https://ably.com/docs/client-lib-development-guide/test-api).
- Integration tests available at [ably-laravel-echo](https://github.com/ably-forks/laravel-echo/tree/master/tests/ably) repository.
## Changelog
Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.
## Contributing
1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Ensure you have added suitable tests and the test suite is passing (run `vendor/bin/phpunit`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create a new Pull Request
## Release Process
This library uses [semantic versioning](http://semver.org/). For each release, the following needs to be done:
1. Create a new branch for the release, named like `release/1.0.6` (where `1.0.6` is what you're releasing, being the new version).
2. Update the lib version in `src/AblyBroadcaster.php`.
3. Run [`github_changelog_generator`](https://github.com/github-changelog-generator/github-changelog-generator) to automate the update of the [CHANGELOG.md](CHANGELOG.md). This may require some manual intervention, both in terms of how the command is run and how the change log file is modified. Your mileage may vary:
- The command you will need to run will look something like this: `github_changelog_generator -u ably -p laravel-broadcaster --since-tag v1.0.6 --output delta.md --token $GITHUB_TOKEN_WITH_REPO_ACCESS`. Generate token [here](https://github.com/settings/tokens/new?description=GitHub%20Changelog%20Generator%20token).
- Using the command above, `--output delta.md` writes changes made after `--since-tag` to a new file.
- The contents of that new file (`delta.md`) then need to be manually inserted at the top of the `CHANGELOG.md`, changing the "Unreleased" heading and linking with the current version numbers.
- Also ensure that the "Full Changelog" link points to the new version tag instead of the `HEAD`.
4. Commit generated [CHANGELOG.md](./CHANGELOG.md) file.
5. Make a PR against `main`.
6. Once the PR is approved, merge it into `main`.
7. Add a tag and push it to origin - e.g.: `git tag v1.0.6 && git push origin v1.0.6`.
8. Visit https://github.com/ably/laravel-broadcaster/tags and add release notes for the release including links to the changelog entry.
9. Visit https://packagist.org/packages/ably/laravel-broadcaster, log in to Packagist, and click the "Update" button.