Ably Broadcaster for Laravel

Ably 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.

This implements ably broadcaster as a independent service provider library for Laravel using ably-php. This library works with the ably-js based ably-laravel-echo client framework with enhanced features. This project is the successor to the pusher-client based ably broadcaster.

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.

Bug Fixes

• Fixes broadcasting events to others.
• 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_DRIVER as ably and specify ABLY_KEY.

BROADCAST_DRIVER=ably
ABLY_KEY=ROOT_API_KEY_COPIED_FROM_ABLY_WEB_DASHBOARD

Warning - Do not expose ABLY_KEY to client code.

2. Uncomment BroadcastServiceProvider in config/app.php

4. If running Laravel 8 or older, edit config/broadcasting.php, add ably section to the connections array

        'ably' => [
            'driver' => 'ably',
            'key' => env('ABLY_KEY')
        ],

Finally, you are ready to install and configure Ably Laravel Echo, which will receive the broadcast events on the client-side.

Using Laravel Echo on client-side

Ably Laravel 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. In this example, we will also install the official ably package:

npm install @ably/laravel-echo ably

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.

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 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:

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.

  // 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.

    ABLY_DISABLE_PUBLIC_CHANNELS=true

• Update ably section under config/broadcasting.php with

        '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.

    ABLY_TOKEN_EXPIRY=21600

• Update ably section under config/broadcasting.php with

        '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.

    ABLY_SYNC_SERVER_TIME=true

• Update ably section under config/broadcasting.php with

        '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, Ably with the Pusher adapter, and all Pusher compatible open source broadcasters. Follow the below steps to migrate from other broadcasters.

1. Leaving a channel

To leave channel on the client side, use Ably Channel Namespaces conventions, instead of Pusher Channel Conventions.

 // 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 emits Ably specific error codes instead of Pusher 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 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 to ably error codes.

    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.

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 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

composer test

• Integration tested using ably sandbox.
• Integration tests available at ably-laravel-echo repository.

Changelog

Please see CHANGELOG 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)
5. Push to the branch (git push origin my-new-feature)
6. Create a new Pull Request

Release Process

This library uses semantic versioning. For each release, the following needs to be done:

1. Create a new branch for the release, named like release/1.2.4 (where 1.2.4 is what you're releasing, being the new version).
2. Update the lib version in src/AblyBroadcaster.php.
3. Run github_changelog_generator to automate the update of the 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.2.4 --output delta.md --token $GITHUB_TOKEN_WITH_REPO_ACCESS. Generate token here.
• 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 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.2.4 && git push origin v1.2.4.
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.