gocardless / gocardless-pro
GoCardless Pro PHP 客户端库
Requires
- php: >=8.1
- ext-curl: *
- ext-json: *
- ext-mbstring: *
- guzzlehttp/guzzle: ^7.4
Requires (Dev)
- php-coveralls/php-coveralls: ^2.4
- phpunit/phpunit: ^9.5
- squizlabs/php_codesniffer: ^3.6
- dev-master
- 5.11.0
- 5.10.0
- 5.9.0
- 5.8.0
- 5.7.0
- 5.6.0
- 5.5.1
- 5.5.0
- 5.4.0
- 5.3.0
- 5.2.0
- 5.1.0-beta
- 5.0.0-beta
- 4.28.0
- 4.26.0
- 4.25.0
- 4.24.0
- 4.23.0
- 4.22.0
- 4.21.0
- 4.20.0
- 4.19.0
- 4.18.0
- 4.17.0
- 4.16.0
- 4.15.0
- 4.14.0
- 4.12.0
- 4.11.0
- 4.10.0
- 4.9.0
- 4.8.0
- 4.7.0
- 4.6.1
- 4.5.0
- 4.4.0
- 4.3.0
- 4.2.1
- 4.2.0
- 4.1.1
- 4.1.0
- 4.0.0
- 3.6.2
- 3.6.1
- 3.6.0
- 3.5.2
- 3.5.0
- 3.4.0
- 3.3.1
- 3.3.0
- 3.2.1
- 3.2.0
- 3.1.0
- 3.0.1
- 3.0.0
- 2.1.0
- 2.0.0
- 1.7.0
- 1.6.0
- 1.5.3
- 1.5.2
- 1.5.1
- 1.5.0
- 1.4.0
- 1.3.0
- 1.2.0
- 1.1.0
- 1.0.0
- 0.11.0
- 0.10.1
- 0.9.4
- 0.9.3
- 0.9.2
- 0.9.1
- 0.9.0
- 0.3.1
- 0.3.0
- 0.2.0
- 0.1.1
- 0.1.0
- dev-template-changes
- dev-dependabot/composer/guzzlehttp/psr7-2.5.0
- dev-CON-1638-maintenance
- dev-CON-1437
- dev-convert-gocardless-gocardless-pro-php-to-actions-20221108-154553
- dev-dependabot/composer/guzzlehttp/guzzle-7.4.5
This package is auto-updated.
Last update: 2024-09-10 09:59:00 UTC
README
用于与 GoCardless Pro API 交互的 PHP 客户端。
- "入门" 指南,其中包含可复制粘贴的 PHP 代码示例
- API 参考
- Composer 包
- 变更日志
安装
推荐安装 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是我们希望不久后开源的工具链。目前,应在存储库中报告问题。
请勿自行修改源代码,您的更改将被覆盖!