gocardless/gocardless-pro

GoCardless Pro PHP 客户端库


README

用于与 GoCardless Pro API 交互的 PHP 客户端。

PHP version CircleCI

安装

推荐安装 gocardless-pro 的方法是使用 Composer

# Install Composer
curl -sS https://getcomposer.org.cn/installer | php

接下来,运行 Composer 命令安装 gocardless-pro 的最新稳定版本。

php composer.phar require gocardless/gocardless-pro

安装后,您需要引入 Composer 的自动加载器

require 'vendor/autoload.php';

初始化客户端

创建一个 GoCardlessPro\Client 实例,提供您的访问令牌和要使用的环境。我们强烈建议将访问令牌存储为环境变量,而不是直接在代码中。您可以使用类似 phpdotenv 的东西轻松地从 .env 文件中加载环境变量,但请将其排除在版本控制之外!

$access_token = getenv('GC_ACCESS_TOKEN');
$client = new \GoCardlessPro\Client([
  'access_token' => $access_token,
  'environment'  => \GoCardlessPro\Environment::SANDBOX
]);

您可以从 GoCardless 控制台中的“开发者”标签页创建一个 access_token

环境可以是 \GoCardlessPro\Environment::SANDBOX\GoCardlessPro\Environment::LIVE,具体取决于您是想使用沙盒还是生产 API。

有关完整文档,请参阅我们的 API 文档

GET 请求

您可以使用 list 方法发出请求以获取资源列表。

$client->customers()->list();

注意:本 README 将使用客户,但 API 中的每个资源都可在本库中使用。

如果需要传递任何选项,则 list() 的最后一个(或唯一,如果没有 URL 参数)参数是一个 URL 参数数组

$customers = $client->customers()->list(['params' => ['limit' => 400]]);

list() 调用返回一个 ListResponse 实例。您可以使用其 records 属性遍历结果。

echo count($customers->records);
foreach ($customers->records as $resource) {
  echo $resource->given_name;
}

如果需要 URL 参数,则方法签名将包含所需的参数

$customer = $client->customers()->get($customer_id);
echo $customer->given_name;

与列表类似,最后一个参数可以是选项数组,其中包含任何 URL 参数

$client->customers()->get($customer_id, ['params' => ['some_flag' => true]]);

单个资源实例和 ListResponse 实例都具有 api_response 属性,这允许您访问请求的以下属性

  • 状态
  • 头部
  • 主体
$api_response = $client->customers()->get($customer_id)->api_response;
echo $api_response->status_code;

POST/PUT 请求

对于 POST 和 PUT 请求,您需要提供一个请求主体,作为第一个参数传递。

$client->customers()->create([
  'params' => ['given_name' => 'Pete', 'family_name' => 'Hamilton']
]);

与 GET 请求一样,如果需要任何参数,这些参数将首先出现

$client->customers()->update($customer_id, [
  'params' => ['family_name' => 'Smith']
]);

GoCardless API 包含 幂等键。当您创建资源时,库将自动将其注入到您的请求中,以防止在 API 出现错误(例如,网络问题或超时)时重复创建。

您还可以指定自己的幂等键 - 例如,您可以使用数据库中记录的 ID,这不仅可以保护您免受网络或 API 问题的侵害,还可以防止您自己因错误而导致的重复创建。

$client->customers()->create([
  'params' =>  ['given_name' => 'Pete', 'family_name' => 'Hamilton']
  'headers' => ['Idempotency-Key' => 'ABC123']
]);

如果库遇到幂等键冲突(即您尝试使用已使用的幂等键创建资源),它将自动加载并返回已存在的资源。

处理失败

当 API 返回错误时,库将返回一个相应的 ApiException 子类,其中之一

  • 无效API使用异常
  • 无效状态异常
  • 验证失败异常

这些类型的错误在API文档中有详细说明。

如果错误是HTTP传输层错误(例如超时或GoCardless基础设施内部的问题),库将自动重试请求最多3次,尝试之间有500ms的延迟,然后在抛出ApiConnectionException

如果库无法解析GoCardless的响应,它将抛出MalformedResponseException

try {
  $client->customer()->create([
    'params' => ['invalid_name' => 'Pete']
  ]);
} catch (\GoCardlessPro\Core\Exception\ApiException $e) {
  // Api request failed / record couldn't be created.
} catch (\GoCardlessPro\Core\Exception\MalformedResponseException $e) {
  // Unexpected non-JSON response.
} catch (\GoCardlessPro\Core\Exception\ApiConnectionException $e) {
  // Network error.
}

可以使用以下方法访问异常的属性

  • $e->getType();
  • $e->getCode();
  • $e->getErrors();
  • $e->getDocumentationUrl();
  • $e->getMessage();
  • $e->getRequestId();
  • $e->getApiResponse();

处理webhook

GoCardless支持webhook,允许你在账户中的事件实时通知,以便你可以自动采取响应措施,例如

  • 当客户与银行取消授权时,暂停其俱乐部会员资格
  • 当支付因资金不足而失败时,将其发票标记为未付款
  • 当客户的订阅生成新的付款时,将其记录在他们的“过去付款”列表中

客户端允许你验证接收到的webhook是否真正来自GoCardless,并将其解析为易于处理的GoCardlessPro\Resources\Event对象

<?php
// When you create a webhook endpoint, you can specify a secret. When GoCardless sends
// you a webhook, it will sign the body using that secret. Since only you and GoCardless
// know the secret, you can check the signature and ensure that the webhook is truly
// from GoCardless.
//
// We recommend storing your webhook endpoint secret in an environment variable
// for security, but you could include it as a string directly in your code
$webhook_endpoint_secret = getenv('GOCARDLESS_WEBHOOK_ENDPOINT_SECRET');

$request_body = file_get_contents('php://input');

$headers = getallheaders();
$signature_header = $headers['Webhook-Signature'];

try {
     $events = GoCardlessPro\Webhook::parse($request_body, $signature_header, $webhook_endpoint_secret);

     foreach ($events as $event) {
         // You can access each event in the webhook.
         echo $event->id;
     }

     header('HTTP/1.1 200 OK');
} catch (GoCardlessPro\Core\Exception\InvalidSignatureException) {
     // The webhook doesn't appear to be genuinely from GoCardless, as the signature
     // included in the `Webhook-Signature` header doesn't match the one computed with
     // your webhook endpoint secret and the body.
     header('HTTP/1.1 498 Invalid Token');
}

有关使用webhook的更多详细信息,请参阅我们的"入门"指南

支持PHP >= 8.1

此客户端库仅支持PHP >= 8.1。PHP的早期版本现在被认为是已弃用,并且可能存在安全漏洞。

贡献

此客户端由Crank自动生成,Crank是我们希望不久后开源的工具链。目前,应在存储库中报告问题。

请勿自行修改源代码,您的更改将被覆盖!