README

使用PHP SDK为Satori平台创建应用程序，这些应用程序使用RTM进行发布和订阅。

需求

PHP 5.4+（推荐PHP 5.6+）
PHP Composer（可选，推荐）

PHP SDK安装和使用

通过Composer

composer require satori-com/satori-rtm-sdk-php=dev-master

强烈建议在安装SDK时使用版本标签

composer require satori-com/satori-rtm-sdk-php:1.2.3.4

有关PHP SDK包的详细信息和可用版本列表，请参阅此处：https://packagist.org.cn/packages/satori-com/satori-rtm-sdk-php

使用Composer自动加载器将SDK包含到您的PHP文件中

<?php

require('vendor/autoload.php');

通过源代码

将PHP SDK克隆到您的项目（或计算机上的任何目录）

cd /path/to/your/project
git clone git@github.com:satori-com/satori-rtm-sdk-php.git

使用SDK自动加载器将SDK包含到您的PHP文件中

<?php

require('satori-rtm-sdk-php/autoloader.php');

文档和示例

https://satori-com.github.io/satori-rtm-sdk-php/

日志和调试

PHP SDK将信息记录到STDOUT/STDERR。要启用调试级别，将DEBUG_SATORI_SDK环境变量设置为true

$ DEBUG_SATORI_SDK=true php <your_program.php>

或

$ export DEBUG_SATORI_SDK=true
$ php <your_program.php>

调试级别输出所有底层与RTM的通信，以及SDK执行信息。
示例

$ DEBUG_SATORI_SDK=true php <your_program.php>
[info] 2017/07/28 15:35:33.536100 Client: Connecting to endpoint: <YOUR_ENDPOINT>
[info] 2017/07/28 15:35:33.823600 Auth: Starting authentication
[debg] 2017/07/28 15:35:33.824300 SEND> {"action":"auth/handshake","body":{"method":"role_secret","data":{"role":"<YOUR_ROLE>"}},"id":1}
[debg] 2017/07/28 15:35:33.951200 RECV< {"action":"auth/handshake/ok","id":1,"body":{"data":{"nonce":"<nonce>"}}}
[info] 2017/07/28 15:35:33.951600 Auth: Got nonce
[debg] 2017/07/28 15:35:33.951600 SEND> {"action":"auth/authenticate","body":{"method":"role_secret","credentials":{"hash":"<hash>"}},"id":2}
[debg] 2017/07/28 15:35:34.082500 RECV< {"action":"auth/authenticate/ok","id":2,"body":{}}
[info] 2017/07/28 15:35:34.082700 Auth: Successfully authenticated
[debg] 2017/07/28 15:35:34.083100 SEND> {"action":"rtm/publish","body":{"channel":"animals","message":{"who":"zebra","where":[34.134358,-118.321506]}},"id":3}
[debg] 2017/07/28 15:35:34.211700 RECV< {"action":"rtm/publish/ok","body":{"position":"1501256125:2"},"id":3}

测试

PHP SDK使用PHPUnit进行测试。PHPUnit需要PHP 5.6+。尽管PHP SDK本身需要PHP 5.4+，但您必须将PHP版本升级到5.6+。

测试需要有效的RTM端点；RTM凭据应在credentials.json中填充。

credentials.json文件必须包含以下键值对

{
  "endpoint": "wss://<SATORI_HOST>/",
  "appkey": "<APP_KEY>",
  "auth_role_name": "<ROLE_NAME>",
  "auth_role_secret_key": "<ROLE_SECRET_KEY>",
  "auth_restricted_channel": "<CHANNEL_NAME>"
}

endpoint是您的RTM访问的客户特定DNS名称。
appkey是您的应用程序密钥。
auth_role_name是一个允许发布/订阅到auth_restricted_channel的角色名称。不能是default。
auth_role_secret_key是auth_role_name的秘密密钥。
auth_restricted_channel是只允许auth_role_name角色订阅和发布的通道。

您必须使用DevPortal创建角色并设置通道权限。

设置好credentials.json后，使用以下命令运行SDK测试

git clone git@github.com:satori-com/satori-rtm-sdk-php.git
cd satori-rtm-sdk-php
composer install
CREDENTIALS=/full/path/to/credentials.json composer test

要启用测试详细模式，请使用

CREDENTIALS=/full/path/to/credentials.json composer test-verbose

二进制协议

RTM支持CBOR协议以处理二进制数据。
要使用CBOR协议，您必须通过Composer安装PHP SDK：如何通过Composer安装SDK

请参阅examples/cbor.php以获取有关使用CBOR建立连接的更多信息。

持久连接

持久连接是减少执行时间的好方法，因为它使用已经建立的连接。PHP不需要额外的时间来建立新的连接和授权。

但这种方法有一些限制

您不能订阅任何通道。添加此限制是为了避免脚本完成后接收缓冲区溢出的可能情况；
存在PDU冲突的可能情况。脚本可以进行带确认的发布，但不等待来自Satori RTM的回复即完成工作。因为连接未关闭，后续使用该连接的脚本将收到确认，尽管它尚未发送任何内容，或者它将带确认进行发布，但在读取回复时收到来自先前脚本的确认；
PHP SDK保证，如果您从一个脚本启动的不同位置连接到同一主机:端口以建立持久连接，则您将获得相同的RTM客户端实例；

用法

$client = RtmClient::persistentConnection('wss://endpoint.satori.com', 'appkey1234', array(
    'connection_id' => 'connection1', // optional
));
$client->connect();

重要提示

持久连接仅在支持持久连接的环境中工作，例如PHP-FPM模式、FastCGI模式、Apache mod_php等。

故障排除

无法连接到安全端点

症状:

$ php your_app/index.php
[info] 2017/08/03 15:28:22.512700 Client: Connecting to endpoint: wss://<endpoint>.api.satori.com/v2
[erro] 2017/08/03 15:28:22.535000 Failed establish connection to <endpoint>.api.satori.com:443:  (0)

解决方案:

检查您是否能够连接到此端点

$ telnet <endpoint>.api.satori.com 443
Trying 123.123.123.123...
Connected to <endpoint>.api.satori.com.
Escape character is '^]'.

如果您无法连接，请检查您的防火墙设置。

检查PHP SSL设置

$ php -r "print_r(openssl_get_cert_locations());";
Array
(
    [default_cert_file] => /usr/local/etc/openssl/cert.pem
    [default_cert_file_env] => SSL_CERT_FILE
    [default_cert_dir] => /usr/local/etc/openssl/certs
    [default_cert_dir_env] => SSL_CERT_DIR
    [default_private_dir] => /usr/local/etc/openssl/private
    [default_default_cert_area] => /usr/local/etc/openssl
    [ini_cafile] =>
    [ini_capath] =>
)

确保default_cert_file指向现有的证书文件，且default_default_cert_area指向现有目录。

如果您的证书位于其他位置，请在控制窗口中输入以下内容来设置指向证书的环境变量：

$ export SSL_CA_FILE=/new/cert/dir/cert.pem
$ export SSL_CA_PATH=/new/cert/dir/
$ php your_app/index.php

satori-com / satori-rtm-sdk-php

维护者

详细信息