README

Ably 是一个支持实时数字体验的平台。无论是参加虚拟场所的活动、接收实时金融信息，还是监控实时汽车性能数据，消费者都期待作为标准来获得实时数字体验。Ably 提供了一系列 API，用于在 80 个国家的超过 2.5 亿台设备上构建、扩展和实时交付强大的数字体验。像彭博社、HubSpot、Verizon 和 Hopin 这样的组织依赖 Ably 的平台来在全球范围内减轻业务关键实时数据同步日益增长的复杂性。更多信息，请参阅 Ably 文档。

此实现将 ably 广播器作为独立的服务提供程序库用于 Laravel，使用 ably-php。此库与基于 ably-js 的 ably-laravel-echo 客户端框架协同工作，具有增强功能。此项目是基于 pusher-client 的 ably 广播器的后续项目。

特性

原生 ably-js 支持。
客户端事件的低延迟。
为每个用户更新频道权限。
更新令牌有效期。
禁用公共频道。
完全兼容 pusher/pusher 兼容的广播器，请参阅迁移部分。

错误修复

修复了向其他人广播事件的问题。
修复了频道成员断开连接的间歇性问题。

要求

PHP 版本 >= 7.2.0
Laravel 版本 >= 6.0.0

安装

您可以通过 composer 安装此包

composer require ably/laravel-broadcaster

设置

更新 .env 文件，将 BROADCAST_DRIVER 设置为 ably 并指定 ABLY_KEY。

BROADCAST_DRIVER=ably
ABLY_KEY=ROOT_API_KEY_COPIED_FROM_ABLY_WEB_DASHBOARD

警告 - 不要将 ABLY_KEY 暴露给客户端代码。

在 config/app.php 中取消注释 BroadcastServiceProvider。

        /*
         * Application Service Providers...
         */
        App\Providers\AppServiceProvider::class,
        App\Providers\AuthServiceProvider::class,
        App\Providers\BroadcastServiceProvider::class,
        App\Providers\EventServiceProvider::class,
        App\Providers\RouteServiceProvider::class,

如果正在运行 Laravel 8 或更早版本，请编辑 config/broadcasting.php，将 ably 部分添加到 connections 数组中

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

最后，您就可以安装和配置 Ably Laravel Echo，它将在客户端接收广播事件。

在客户端使用 Laravel Echo

Ably Laravel Echo 是一个 JavaScript 库，可以轻松订阅频道并监听由您的服务器端广播驱动程序广播的事件。Ably 维护了官方 laravel-echo 模块的分支，允许您使用官方的 ably-js SDK。在此示例中，我们还将安装官方的 ably 包

npm install @ably/laravel-echo ably@1.x

一旦Echo安装完成，你就可以在你的应用JavaScript中创建一个新的Echo实例。一个很好的做法是在Laravel框架包含的resources/js/bootstrap.js文件底部进行。默认情况下，该文件中已经包含了Echo的示例配置；然而，bootstrap.js文件中的默认配置是为Pusher设计的。你可以复制下面的配置以将你的配置迁移到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');
    }
});

请参阅Ably Laravel Echo文档以获取有关配置Ably特定客户端选项和实现额外功能的更多信息。

一旦你根据自己的需求取消注释并调整Echo配置，你可以编译应用资源

npm run dev

配置高级功能

1. 修改私有/存在频道的功能。默认：全部功能

使用ably-capability分别为每个单独的用户授予频道访问控制权限。它定义了根据频道功能的访问声明列表。

  // 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. 禁用公共频道。默认：false

在.env文件中将ABLY_DISABLE_PUBLIC_CHANNELS设置为true。

    ABLY_DISABLE_PUBLIC_CHANNELS=true

在config/broadcasting.php中的Ably部分更新为

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

3. 更新令牌过期时间。默认：3600秒（1小时）

在.env文件中设置ABLY_TOKEN_EXPIRY。

    ABLY_TOKEN_EXPIRY=21600

在config/broadcasting.php中的Ably部分更新为

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

4. 使用发行令牌的互联网时间。默认：false

如果启用此选项，将从Ably服务获取UTC格式的互联网时间并每6小时缓存一次。
此选项在服务器上使用laravel-broadcaster时很有用，因为某种原因，无法通过常规方式同步服务器时钟。
在.env文件中将ABLY_SYNC_SERVER_TIME设置为true。

    ABLY_SYNC_SERVER_TIME=true

在config/broadcasting.php中的Ably部分更新为

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

从pusher/pusher兼容的广播器迁移

Ably Laravel广播器旨在与所有Laravel广播提供者兼容，例如Pusher，带有Pusher适配器的Ably，以及所有Pusher兼容的开源广播器。按照以下步骤从其他广播器迁移。

1. 离开频道

要客户端上离开频道，请使用Ably频道命名空间约定，而不是Pusher频道约定。

 // 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. 错误处理

请注意，Ably laravel-echo客户端发出的是Ably特定错误代码，而不是Pusher错误代码。
Ably发出的错误是描述性的，易于理解，因此可以更有效地采取纠正措施。
Ably错误以包含完整错误上下文的ErrorInfo对象提供。
如果你在与pusher错误交互的项目中，请确保相应地更新你的代码。即从pusher错误代码更新到ably错误代码。

    channel.error(error => {
        if (error && error.code === 40142) { // ably token expired
            console.error(error);
            // take corrective action on UI
        }
    })

注意

在 Echo.join().here(members => {}) 实现中，每当一个客户端 加入、更新或离开 频道时，成员都会被更新，而使用 Pusher 时，这只会对第一个进入频道的客户端调用一次。
Ably 的行为遵循标准的 Echo 存在频道接口 here 方法。

附加文档

当前 README 覆盖了为设置 laravel 应用并运行它而进行的基本的 ably 广播器+echo 配置。
有关广播和接收事件的更多信息，请参阅 Laravel 广播文档。

示例

我们使用基于 laravel 的 Ably Broadcaster+Echo 创建了一个演示网页聊天应用。
请访问 https://github.com/ably-labs/laravel-broadcast-app 获取详细信息。

测试

要运行测试，请使用

composer test

使用 ably 沙箱进行集成测试。
集成测试可在 ably-laravel-echo 仓库中找到。

变更日志

请参阅 CHANGELOG 了解最近更改的详细信息。

贡献

将其分叉
创建您的功能分支（git checkout -b my-new-feature）
提交您的更改（git commit -am 'Add some feature'）
确保您已添加合适的测试，并且测试套件正在通过（运行 vendor/bin/phpunit）
将分支推送到远程（git push origin my-new-feature）
创建一个新的拉取请求

发布流程

此库使用语义版本控制。对于每个版本，需要执行以下操作

为发布创建一个新分支，例如命名为 release/1.2.4（其中 1.2.4 是您要发布的版本，是新版本）。
更新 src/AblyBroadcaster.php 中的库版本。
运行 github_changelog_generator 以自动化更新 CHANGELOG.md。这可能需要一些手动干预，包括如何运行命令以及如何修改更改日志文件。效果可能因人而异

您需要运行的命令可能看起来像这样：github_changelog_generator -u ably -p laravel-broadcaster --since-tag v1.2.4 --output delta.md --token $GITHUB_TOKEN_WITH_REPO_ACCESS。在此处生成令牌这里。
使用上述命令，--output delta.md 将在 --since-tag 之后所做的更改写入新文件。
该新文件（delta.md）的内容需要手动插入到 CHANGELOG.md 的顶部，更改“未发布”标题，并将其链接到当前版本号。
同时确保“完整更改日志”链接指向新版本标签而不是 HEAD。

提交生成的 CHANGELOG.md 文件。
针对 main 提交一个 PR。
一旦 PR 被批准，将其合并到 main。
添加标签并将其推送到 origin - 例如：git tag v1.2.4 && git push origin v1.2.4。
访问 https://github.com/ably/laravel-broadcaster/tags 并为发布添加发布说明，包括指向更改日志条目的链接。
访问 https://packagist.org.cn/packages/ably/laravel-broadcaster，登录到Packagist，然后点击“更新”按钮。

ably / laravel-broadcaster

维护者

详细信息