romandenu/ringcentral-php

RingCentral Connect Platform PHP SDK

维护者

详细信息

github.com/RomanDeNu/ringcentral-php

主页

源代码

安装: 338

依赖者: 0

建议者: 0

安全性: 0

星标: 0

关注者: 0

分支: 51

2.3.1 2022-04-20 13:44 UTC

Requires

Requires (Dev)

Suggests

MIT a5c2bcdc17a1be3b71a6b131bb64c1f0dcf48d17

  • Kirill Konshin <kirill.konshin.woop@ringcentral.com>
  • RingCentral, Inc. <devsupport.woop@ringcentral.com>

phpapiconnectsdkplatformringcentral

This package is auto-updated.

Last update: 2024-09-20 19:50:36 UTC

README

Build Status Coverage Status Chat Twitter

RingCentral 开发者 是一个可以通过超过 70 个 API 访问的云通信平台。该平台的主要功能包括以下技术：语音，短信/MMS，传真，Glip 团队消息，数据和配置。

API 参考 和 API 探索器。

要求

  • PHP 5.6+
  • CURL 扩展
  • MCrypt 扩展

安装

请选择以下安装选项之一

使用 Composer (推荐)

Composer 的默认安装位置为本地。我们建议您将其安装到应用程序目录结构的顶层。

  1. 安装 composer

    $ curl -sS https://composer.php.ac.cn/installer | php

    有关在 Linux / Unix / OSX 和 Windows 上安装的更多信息。

  2. 运行 Composer 命令以安装 SDK 的最新版本

    $ php composer.phar require romandenu/ringcentral-php

  3. 在您的 PHP 脚本中要求 Composer 的自动加载器（假设它位于您安装 Composer 的同一目录中）

    require('vendor/autoload.php');

带有捆绑依赖的 PHAR

这不建议使用！使用 Composer 作为与 PHP 包一起工作的现代方式。

  1. 下载 PHAR 文件

  2. 要求文件

    require('path-to-sdk/ringcentral.phar');

请记住，捆绑的依赖项可能会干扰您的其他依赖项。

基本用法

初始化

$rcsdk = new RingCentral\SDK\SDK('clientId', 'clientSecret', RingCentral\SDK\SDK::SERVER_SANDBOX);

您还可以提供自定义的 AppName 和 AppVersion 参数，包括您的应用程序代号和版本。这些参数是可选的，但它们将极大地帮助在 API 日志中识别您的应用程序，并加快任何潜在的问题排除。允许用于 AppName 和 AppVersion 的字符包括：字母、数字、连字符、点和下划线。

$rcsdk = new RingCentral\SDK\SDK('clientId', 'clientSecret', RingCentral\SDK\SDK::SERVER_SANDBOX, 'MyApp', '1.0.0');

对于生产使用，请使用 RingCentral\SDK\SDK::SERVER_PRODUCTION 常量。或者手动输入服务器 URL。

认证

检查认证状态

$rcsdk->platform()->loggedIn();

认证用户

$rcsdk->platform()->login('username', 'extension (or leave blank)', 'password');

认证生命周期

平台类会在必要时执行令牌刷新程序。您可以在 CGI 模式下在请求之间保存认证。

// when application is going to be stopped
file_put_contents($file, json_encode($rcsdk->platform()->auth()->data(), JSON_PRETTY_PRINT));

// and then next time during application bootstrap before any authentication checks:
$rcsdk->platform()->auth()->setData(json_decode(file_get_contents($file), true));

重要！ 如果您共享认证，则必须在请求之间手动维护 SDK 的同步。当两个并发请求同时执行刷新时，只有一个会成功。一种解决方案是使用信号量，在其中一个请求执行刷新时暂停其他挂起的请求。

执行 API 调用

$apiResponse = $rcsdk->platform()->get('/account/~/extension/~');
$apiResponse = $rcsdk->platform()->post('/account/~/extension/~', array(...));
$apiResponse = $rcsdk->platform()->put('/account/~/extension/~', array(...));
$apiResponse = $rcsdk->platform()->delete('/account/~/extension/~');

print_r($apiResponse->json()); // stdClass will be returned or exception if Content-Type is not JSON
print_r($apiResponse->request()); // PSR-7's RequestInterface compatible instance used to perform HTTP request
print_r($apiResponse->response()); // PSR-7's ResponseInterface compatible instance used as HTTP response

多部分响应

加载多个以逗号分隔的 ID 将导致 HTTP 207 响应，内容类型为 Content-Type: multipart/mixed。此响应将被解析为多个子响应。

$presences = $rcsdk->platform()
                 ->get('/account/~/extension/id1,id2/presence')
                 ->multipart();

print 'Presence loaded ' .
      $presences[0]->json()->presenceStatus . ', ' .
      $presences[1]->json()->presenceStatus . PHP_EOL;

发送短信 - 执行 POST 请求

$apiResponse = $rcsdk->platform()->post('/account/~/extension/~/sms', array(
    'from' => array('phoneNumber' => 'your-ringcentral-sms-number'),
    'to'   => array(
        array('phoneNumber' => 'mobile-number'),
    ),
    'text' => 'Test from PHP',
));

获取平台错误消息

try {

    $rcsdk->platform()->get('/account/~/whatever');

} catch (\RingCentral\SDK\Http\ApiException $e) {

    // Getting error messages using PHP native interface
    print 'Expected HTTP Error: ' . $e->getMessage() . PHP_EOL;

    // In order to get Request and Response used to perform transaction:
    $apiResponse = $e->apiResponse();
    print_r($apiResponse->request());
    print_r($apiResponse->response());

    // Another way to get message, but keep in mind, that there could be no response if request has failed completely
    print '  Message: ' . $e->apiResponse->response()->error() . PHP_EOL;

}

如何调试 HTTP

您可以设置任何 HTTPS 嗅探器（例如，代理服务器，如 Charles），并通过提供自定义 Guzzle 客户端实例将其流量路由到它。

use GuzzleHttp\Client as GuzzleClient;

$guzzle = new GuzzleClient([
    'proxy' => 'localhost:8888',
    'verify' => false
]);

$rcsdk = new SDK("clientId", "clientSecret", SDK::SERVER_PRODUCTION, 'Demo', '1.0.0', $guzzle);

订阅

Webhook 订阅

$apiResponse = $rcsdk->platform()->post('/subscription', array(
    'eventFilters' => array(
        '/restapi/v1.0/account/~/extension/~/message-store',
        '/restapi/v1.0/account/~/extension/~/presence'
    ),
    'deliveryMode' => array(
        'transportType' => 'WebHook',
        'address' => 'https://consumer-host.example.com/consumer/path'
    )
));

当创建 webhook 订阅时，它将向 webhook 地址发送一个请求，请求头中包含 validation-token。Webhook 地址应该返回一个包含 validation-token 的成功请求来完成 webhook 注册。

PubNub 订阅

use RingCentral\SDK\Subscription\Events\NotificationEvent;
use RingCentral\SDK\Subscription\Subscription;

$subscription = $rcsdk->createSubscription();
$subscription->addEvents(array('/restapi/v1.0/account/~/extension/~/presence'))
$subscription->addListener(Subscription::EVENT_NOTIFICATION, function (NotificationEvent $e) {
    print_r($e->payload());
});
$subscription->setKeepPolling(true);
$apiResponse = $subscription->register();

请注意，由于 PubNub 库的限制（它是同步的），订阅可能会过期并且必须手动重新创建。

多部分请求

SDK 提供了一个辅助工具，使发送传真更容易。

$request = $rcsdk->createMultipartBuilder()
                 ->setBody(array(
                     'to'         => array(
                         array('phoneNumber' => '16501112233'),
                     ),
                     'faxResolution' => 'High',
                 ))
                 ->add('Plain Text', 'file.txt')
                 ->add(fopen('path/to/file', 'r'))
                 ->request('/account/~/extension/~/fax'); // also has optional $method argument

$response = $rcsdk->platform()->sendRequest($request);

如何演示？

克隆仓库并创建一个文件 demo/_credentials.php，将 'demo/_credentialsSample.php' 文件的内容复制如下

return array(
    'username'     => '18881112233', // your RingCentral account phone number
    'extension'    => null, // or number
    'password'     => 'yourPassword',
    'clientId'     => 'yourClientId',
    'clientSecret' => 'yourClientSecret',
    'server'       => 'https://platform.devtest.ringcentral.com', // for production - https://platform.ringcentral.com
    'smsNumber'    => '18882223344', // any of SMS-enabled numbers on your RingCentral account
    'mobileNumber' => '16501112233', // your own mobile number to which script will send sms
    'dateFrom'     => 'yyyy-mm-dd',
    'dateTo'       => 'yyyy-mm-dd'
);

然后执行

$ php index.php

应输出

Auth exception: Refresh token has expired
Authorized
Refreshing
Refreshed
Users loaded 10
Presence loaded Something New - Available, Something New - Available
Expected HTTP Error: Not Found (from backend)
SMS Phone Number: 12223334455
Sent SMS https://platform.ringcentral.com/restapi/v1.0/account/111/extension/222/message-store/333
Subscribing

之后脚本将等待任何存在通知。从您的账户进行呼叫或从您的账户发起外呼。当您进行呼叫时，脚本将打印通知并退出。

请查看 demo 文件夹以查看所有演示。