Recurly PHP客户端技术文档

1. 安装指南

1.1 使用Composer安装

Recurly PHP客户端通过Packagist发布，包名为recurly/recurly-client。推荐使用Composer来安装和维护该依赖。

在项目的composer.json文件中添加以下内容：

{
    "require": {
        "recurly/recurly-client": "^4"
    }
}

然后运行以下命令进行安装：

composer install

1.2 注意事项

• Recurly PHP客户端遵循语义化版本控制（Semantic Versioning），只有在主版本更新时才会引入破坏性更改。
• 如果你需要使用V2版本的客户端，请参考v2分支。

2. 项目的使用说明

2.1 创建客户端

在使用Recurly API之前，首先需要创建一个客户端实例。客户端的构造函数需要一个API密钥，该密钥可以在Recurly的API Credentials Page获取。

$api_key = 'myApiKey';
$client = new \Recurly\Client($api_key);

如果你在欧洲地区使用Recurly API，需要在选项中指定region为eu：

$api_key = 'myApiKey';
$client = new \Recurly\Client($api_key, ['region' => 'eu']);

2.2 日志记录

客户端的构造函数还支持传入一个日志记录器。日志记录器需要实现PSR-3 Logger Interface。默认情况下，客户端会创建一个\Recurly\Logger实例，该实例会将日志消息打印到php://stdout，日志级别为\Psr\Log\LogLevel::WARNING。

$logger = new \Recurly\Logger('Recurly', \Psr\Log\LogLevel::INFO);
$client = new \Recurly\Client($api_key, $logger);

安全警告：在生产环境中，日志级别不应设置为DEBUG，否则可能会导致敏感数据泄露。

2.3 操作方法

\Recurly\Client类包含了所有可以在Recurly API上执行的操作方法。每个方法都有详细的文档说明，解释了输入和返回类型的类型和描述。例如，要使用get_plan端点，可以调用Client#getPlan()方法：

$plan_code = "gold";
$plan = $client->getPlan("code-$plan_code");

2.4 分页处理

分页通过\Recurly\Pager对象实现。Pager对象由客户端的list*方法创建，并实现了PHP的Iterator接口，因此可以在foreach循环中使用。

$accounts = $client->listAccounts();

foreach($accounts as $account) {
    echo 'Account code: ' . $account->getCode() . PHP_EOL;
}

2.5 排序和过滤

在调用list*方法时，可以传入选项参数来进行排序或过滤。这些参数在方法文档中有所描述，可以在Recurly API文档的“Query Parameters”部分找到。

$options = array('params' => array(
    'limit' => 200,
    'order' => 'asc',
    'begin_time' => '2020-01-01T01:00:00Z',
    'end_time' => '2020-02-01T01:00:00Z',
    'email' => '[e-mail]',
    'subscriber' => true,
    'past_due' => false
));
$accounts = $client->listAccounts($options);

foreach($accounts as $account) {
    echo 'Account code: ' . $account->getCode() . PHP_EOL;
}

2.6 资源计数

Pager类实现了getCount()方法，可以获取Pager对象将返回的资源总数。该方法通过调用端点的HEAD请求并解析Recurly-Total-Records头来实现。

$accounts = $client->listAccounts([ 'past_due' => true ]);
$count = $accounts->getCount();
echo "Number of accounts past due: $count"

2.7 高效获取第一个或最后一个资源

Pager类还实现了getFirst()方法，可以高效地获取第一个或最后一个资源。

$accounts = $client->listAccounts([ 'order' => 'desc', 'past_due' => true ]);
$account = $accounts->getFirst();

3. 项目API使用文档

3.1 创建资源

对于创建或更新资源，可以传入一个普通的关联数组给create*或update*方法。

$plan_create = array(
    "name" => "Monthly Coffee Subscription",
    "code" => "coffee-monthly",
    "currencies" => [
        array(
            "currency" => "USD",
            "unit_amount" => 20.0
        )
    ]
);

$plan = $client->createPlan($plan_create);

echo 'Created Plan:' . PHP_EOL;
var_dump($plan);

3.2 错误处理

在调用API时，可能会遇到各种错误。可以通过捕获异常来处理这些错误。

try {
    $account = $client->deactivateAccount($account_id);
} catch (\Recurly\Errors\Validation $e) {
    var_dump($e);
} catch (\Recurly\Errors\NotFound $e) {
    var_dump($e);
} catch (\Recurly\RecurlyError $e) {
    var_dump($e);
}

3.3 HTTP元数据

有时你可能需要获取底层HTTP请求和响应的额外信息。可以通过调用getResponse()方法来访问这些信息。

$account = $client->getAccount("code-douglas");
$response = $account->getResponse();
echo "Request ID:" . $response->getRequestId() . PHP_EOL;
echo "Rate limit remaining:" . $response->getRateLimitRemaining() . PHP_EOL;

4. 项目安装方式

项目通过Composer进行安装，具体步骤请参考安装指南。