README

文档

Reach API 的文档可以在这里找到。

PHP 库的文档可以在这里找到。

版本

reach-php 对所有更改使用修改版的 语义化版本控制。 请参阅此文档以获取详细信息。

支持的 PHP 版本

此库支持以下 PHP 实现

• PHP 7.2
• PHP 7.3
• PHP 7.4
• PHP 8.0
• PHP 8.1

安装

您可以通过 composer 或下载源代码来安装 reach-php。

通过 Composer

reach-php 作为 talkylabs/reach-sdk 包在 Packagist 上可用

composer require talkylabs/reach-sdk

测试您的安装

以下是一个使用 SDK 发送文本消息的示例

// Send an SMS using Reach's REST API and PHP
<?php
// Required if your environment does not handle autoloading
require __DIR__ . '/vendor/autoload.php';

// Your ApiUser and ApiKey Token from the web application
$apiUser = "XXXXXXXX";
$apiKey = "YYYYYY";
$client = new Reach\Rest\Client($apiUser, $apiKey);

// Use the Client to make requests to the Reach REST API
$client->messaging->messagingItems->send(
    '+15558675309', '+15017250604', "Hey Jenny! Good luck on the bar exam!"
);

不使用 Composer

虽然我们建议使用包管理器来跟踪您应用程序的依赖关系，但手动下载和使用 PHP SDK 是可能的。您可以从 GitHub 下载 PHP SDK 的完整源代码，如果您想的话还可以浏览仓库。要在您的应用程序中使用 SDK，请将 SDK 下载文件解压缩到与您的 PHP 代码相同的目录中。然后，您可以在代码中包含 SDK 附加的自动加载文件。

<?php
// Require the bundled autoload file - the path may need to change
// based on where you downloaded and unzipped the SDK
require __DIR__ . '/reach-php-main/src/Reach/autoload.php';

// Your ApiUser and ApiKey Token from the web application
$apiUser = "XXXXXXXX";
$apiKey = "YYYYYY";
$client = new Reach\Rest\Client($apiUser, $apiKey);

// Use the Client to make requests to the Reach REST API
$client->messaging->messagingItems->send(
    // The number you'd like to send the message to
    '+15558675309', '+15017250604', "Hey Jenny! Good luck on the bar exam!"
);

警告 在本地测试时，您可以硬编码凭据，但在提交任何代码或部署到生产之前，您应使用环境变量来保持它们的安全。

用法

获取消息项

<?php
require_once '/path/to/vendor/autoload.php';

$apiUser = "XXXXXXXX";
$apiKey = "YYYYYY";
$client = new Reach\Rest\Client($apiUser, $apiKey);

// Get an object using its SID. If you do not have a SID,
// check out the list resource examples on this page
$msg = $client->messaging->messagingItems()->fetch("XXed11f93dc08b952027ffbc406d0868");
print $msg->dest;

遍历记录

库自动为您处理分页。集合，如 messagingItems，具有在底层分页的 read 和 stream 方法。使用 read 和 stream，您可以指定您希望接收的记录数（limit）和每页检索的最大大小（pageSize）。然后，库将为您处理任务。

read 会预先获取所有记录并以列表形式返回，而 stream 则返回一个迭代器，并在遍历集合时懒性地检索记录页。您还可以使用 page 方法手动分页。

使用 read 方法

<?php
require_once '/path/to/vendor/autoload.php';

$apiUser = "XXXXXXXX";
$apiKey = "YYYYYY";
$client = new Reach\Rest\Client($apiUser, $apiKey);

// Loop over the list of messagingItems and print a property from each one
foreach ($client->messaging->messagingItems->read() as $msg) {
    print $msg->dest;
}

启用调试日志

默认 HTTP 客户端有两种方法可以启用调试日志。您可以创建一个名为 REACH_TALKYLABS_LOG_LEVEL 的环境变量并将其设置为 debug，或者您可以将日志级别设置为调试

$apiUser = "XXXXXXXX";
$apiKey = "YYYYYY";

$client = new Reach\Rest\Client($apiUser, $apiKey);
$client->setLogLevel('debug');

处理异常

当客户端初始化或 API 请求中出现问题时，reach-php 将抛出适当的异常。您应该处理这些异常以保持应用程序运行并避免不必要的崩溃。

Reach 客户端

例如，当初始化客户端时可能会出现身份验证异常，可能是由于凭据错误。可以这样处理

<?php
require_once('/path/to/reach-php/Services/Reach.php');

use Reach\Exceptions\ConfigurationException;
use Reach\Rest\Client;

$apiUser = "XXXXXXXX";
$apiKey = "YYYYYY";

// Attempt to create a new Client, but your credentials may contain a typo
try {
    $client = new Reach\Rest\Client($apiUser, $apiKey);
} catch (ConfigurationException $e) {
    // You can `catch` the exception, and perform any recovery method of your choice
    print $e . getCode();
}

$msg = $client->messaging->messagingItems()->
    ->fetch("XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX");

print $msg->dest;

CurlClient

在初始化 curl 客户端时，如果您的系统上未安装 curl，您将看到 EnvironmentException。

<?php
require_once('/path/to/reach-php/Services/Reach.php');

use Reach\Exceptions\ReachException;
use Reach\Http\CurlClient;

$apiUser = "XXXXXXXX";
$apiKey = "YYYYYY";
$client = new Reach\Rest\Client($apiUser, $apiKey);

try {
    $client = new CurlClient();

    $client->options(
        'GET',
        'http://api.reach.talkylabs.com',
        array(),
        array(),
        array(),
        $apiUser,
        $apiKey
    );
} catch (EnvironmentException $e) {
    print $e . getCode();
}

ReachException

ReachException 可以用来处理API错误，如下所示。这是您最有可能使用的最常见异常类型。

<?php
require_once('/path/to/reach-php/Services/Reach.php');

use Reach\Exceptions\ReachException;

$apiUser = "XXXXXXXX";
$apiKey = "YYYYYY";
$client = new Reach\Rest\Client($apiUser, $apiKey);

try {
    $msg = $client->messaging->messagingItems()->fetch("XXed11f93dc08b952027ffbc406d0868");
} catch (ReachException $e) {
    print $e->getCode();
}

print $msg->dest;

调试API请求

为了帮助调试，该库允许您访问底层的请求和响应对象。这种能力是集成在库中提供的默认Curl客户端中的。

例如，您可以像这样检索最后响应的状态码

<?php
$apiUser = "XXXXXXXX";
$apiKey = "YYYYYY";

$client = new Reach\Rest\Client($apiUser, $apiKey);
$message = $client->messaging->messagingItems->send(
    '+15558675309', '+15017250604', "Hey Jenny! Good luck on the bar exam!"
);

// Print the message's SID
print $message->messageId;

// Print details about the last request
print $client->lastRequest->method;
print $client->lastRequest->url;
print $client->lastRequest->auth;
print $client->lastRequest->params;
print $client->lastRequest->headers;
print $client->lastRequest->data;

// Print details about the last response
print $client->lastResponse->statusCode;
print $client->lastResponse->body;

使用自定义HTTP客户端

要使用此辅助库与自定义HTTP客户端，请参阅 如何实现的高级示例。

Docker镜像

本存储库中存在的 Dockerfile 以及相应的 talkylabs/reach-php Docker镜像目前仅供TalkyLabs进行测试使用。

获取帮助

如果您在库中发现了错误或希望添加新功能，请在此存储库中创建问题或提交拉取请求！