gocardless pro php
v6.0.0
PHP-клиент для взаимодействия с API GoCardless Pro.
Рекомендуемый способ установки gocardless-pro — использовать Composer.
# Install Composer
curl -sS https://getcomposer.org/installer | php Затем запустите команду Composer, чтобы установить последнюю стабильную версию gocardless-pro .
php composer.phar require gocardless/gocardless-proПосле установки вам потребуется автозагрузчик Composer:
require ' vendor/autoload.php ' ; Создайте экземпляр GoCardlessProClient , предоставив свой токен доступа и среду, которую вы хотите использовать. Мы настоятельно рекомендуем хранить токен доступа как переменную среды, а не непосредственно в коде. Вы можете легко загрузить переменные среды из файла .env , используя что-то вроде phpdotenv, но держите его вне контроля версий!
$ access_token = getenv ( ' GC_ACCESS_TOKEN ' );
$ client = new GoCardlessPro Client ([
' access_token ' => $ access_token ,
' environment ' => GoCardlessPro Environment :: SANDBOX
]); Вы можете создать access_token на вкладке «Разработчики» на панели инструментов GoCardless.
Средой может быть GoCardlessProEnvironment::SANDBOX или GoCardlessProEnvironment::LIVE , в зависимости от того, хотите ли вы использовать песочницу или живой API.
Полную документацию можно найти в нашей документации по API.
Вы можете сделать запрос на получение списка ресурсов, используя метод list .
$ client -> customers ()-> list ();Примечание. В этом README будут использоваться клиенты, но каждый из ресурсов API доступен в этой библиотеке.
Если вам нужно передать какие-либо параметры, последний (или единственный, при отсутствии параметров URL) аргумент list() представляет собой массив параметров 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 , который позволяет получить доступ к следующим свойствам запроса:
statusheadersbody $ api_response = $ client -> customers ()-> get ( $ customer_id )-> api_response ;
echo $ api_response -> status_code ;Для запросов 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 (например, проблемы с сетью или тайм-аут).
Вы также можете указать свой собственный ключ идемпотентности — вы можете, например, использовать идентификаторы записей в вашей базе данных, защищая себя не только от проблем с сетью или API, но и от ошибок на вашей стороне, которые могут привести к двойному созданию:
$ client -> customers ()-> create ([
' params ' => [ ' given_name ' => ' Pete ' , ' family_name ' => ' Hamilton ' ]
' headers ' => [ ' Idempotency-Key ' => ' ABC123 ' ]
]);Если библиотека сталкивается с конфликтом ключей идемпотентности (то есть вы пытаетесь создать ресурс с уже использованным ключом идемпотентности), она автоматически загрузит и вернет уже существующий ресурс.
Когда API возвращает ошибку, библиотека вернет соответствующий подкласс ApiException , один из:
InvalidApiUsageExceptionInvalidStateExceptionValidationFailedExceptionЭти типы ошибок описаны в документации API.
Если ошибка связана с ошибкой транспортного уровня HTTP (например, таймауты или проблемы в инфраструктуре GoCardless), запросы будут автоматически повторяться библиотекой до 3 раз с задержкой 500 мс между попытками, прежде чем возникнет исключение 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();GoCardless поддерживает веб-перехватчики, позволяя вам получать уведомления в режиме реального времени, когда что-то происходит в вашей учетной записи, поэтому вы можете предпринимать автоматические ответные действия, например:
Клиент позволяет вам проверить, что полученный вами вебхук действительно принадлежит GoCardless, и проанализировать его на объекты GoCardlessProResourcesEvent , с которыми легко работать:
// 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 ' );
}Дополнительные сведения о работе с веб-перехватчиками см. в нашем руководстве «Начало работы».
Эта клиентская библиотека поддерживает только PHP >= 8.1. Более ранние версии PHP теперь считаются устаревшими и могут иметь уязвимости безопасности.
Этот клиент автоматически создается на основе Crank, набора инструментов, исходный код которого мы надеемся вскоре открыть. На данный момент о проблемах следует сообщать в этом репозитории.
Пожалуйста, не изменяйте исходный код самостоятельно, ваши изменения будут отменены!
