stripe php

Привязки PHP Stripe

PHP-библиотека Stripe обеспечивает удобный доступ к Stripe API из приложений, написанных на языке PHP. Он включает в себя предопределенный набор классов для ресурсов API, которые динамически инициализируются на основе ответов API, что делает его совместимым с широким спектром версий Stripe API.

Требования

PHP 5.6.0 и более поздние версии.

Композитор

Вы можете установить привязки через Composer. Выполните следующую команду:

composer require stripe/stripe-php

Чтобы использовать привязки, используйте автозагрузку Composer:

 require_once ' vendor/autoload.php ' ;

Ручная установка

Если вы не хотите использовать Composer, вы можете загрузить последнюю версию. Затем, чтобы использовать привязки, включите файл init.php .

 require_once ' /path/to/stripe-php/init.php ' ;

Зависимости

Для правильной работы привязок требуются следующие расширения:

• curl , хотя вы можете использовать свой собственный клиент, отличный от cURL, если хотите.
• json
• mbstring (многобайтовая строка)

Если вы используете Composer, эти зависимости должны обрабатываться автоматически. Если вы устанавливаете вручную, вам необходимо убедиться, что эти расширения доступны.

Начиная

Простое использование выглядит так:

 $ stripe = new  Stripe  StripeClient ( ' sk_test_BQokikJOvBiI2HlWgH4olfQ2 ' );
$ customer = $ stripe -> customers -> create ([
    ' description ' => ' example customer ' ,
    ' email ' => ' [email protected] ' ,
    ' payment_method ' => ' pm_card_visa ' ,
]);
echo $ customer ;

Шаблоны клиент/сервис против устаревших шаблонов

Вы можете продолжать использовать устаревшие шаблоны интеграции, использовавшиеся до версии 7.33.0. Ознакомьтесь с руководством по миграции, чтобы узнать об изменениях обратно совместимых шаблонов клиентов и служб.

Документация

См. документацию PHP API.

Посмотрите видеодемонстрации, рассказывающие о том, как использовать библиотеку.

Поддержка устаревших версий

PHP 5.4 и 5.5

Если вы используете PHP 5.4 или 5.5, вам следует рассмотреть возможность обновления вашей среды, поскольку срок использования этих версий истек с сентября 2015 года и июля 2016 года соответственно. В противном случае вы все равно можете использовать Stripe, загрузив Stripe-php v6.43.1 (zip, tar.gz) с нашей страницы релизов. Эта версия будет работать, но может не поддерживать последние функции, которые мы добавили с момента выпуска версии, и лучшим решением будет обновление PHP.

PHP 5.3

Если вы используете PHP 5.3, вам следует обновить свою среду, поскольку срок службы этой версии истек с августа 2014 года. В противном случае вы можете загрузить версию 5.9.2 (zip, tar.gz) с нашей страницы выпусков. Эта версия продолжит работать с новыми версиями Stripe API для всех распространенных целей.

Таймауты пользовательских запросов

Примечание. Мы не рекомендуем уменьшать тайм-аут для вызовов, не предназначенных только для чтения (например, создание оплаты), поскольку даже если вы локально истечете тайм-аут, запрос на стороне Stripe все равно может быть выполнен. Если вы уменьшаете тайм-ауты для этих вызовов, обязательно используйте токены идемпотентности, чтобы избежать выполнения одной и той же транзакции дважды в результате логики повтора тайм-аута.

Чтобы изменить время ожидания запроса (подключение или общее количество в секундах), вам нужно указать клиенту API использовать CurlClient, отличный от его по умолчанию. Вы установите таймауты в этом CurlClient.

 // set up your tweaked Curl client
$ curl = new  Stripe  HttpClient  CurlClient ();
$ curl -> setTimeout ( 10 ); // default is StripeHttpClientCurlClient::DEFAULT_TIMEOUT
$ curl -> setConnectTimeout ( 5 ); // default is StripeHttpClientCurlClient::DEFAULT_CONNECT_TIMEOUT

echo $ curl -> getTimeout (); // 10
echo $ curl -> getConnectTimeout (); // 5

// tell Stripe to use the tweaked client
 Stripe  ApiRequestor :: setHttpClient ( $ curl );

// use the Stripe API client as you normally would 

Пользовательские параметры cURL (например, прокси)

Вам нужно установить прокси для ваших запросов? Передайте необходимый массив CURLOPT_* конструктору CurlClient, используя тот же синтаксис, что и curl_stopt_array() . Это установит параметры cURL по умолчанию для каждого HTTP-запроса, сделанного SDK, хотя многие более распространенные параметры (например, тайм-ауты; как их установить, см. выше) будут переопределены клиентом, даже если они установлены здесь.

 // set up your tweaked Curl client
$ curl = new  Stripe  HttpClient  CurlClient ([ CURLOPT_PROXY => ' proxy.local:80 ' ]);
// tell Stripe to use the tweaked client
 Stripe  ApiRequestor :: setHttpClient ( $ curl );

Альтернативно, вызываемый объект может быть передан конструктору CurlClient, который возвращает вышеуказанный массив на основе входных данных запроса. См. testDefaultOptions() в tests/CurlClientTest.php пример такого поведения. Обратите внимание, что вызываемый объект вызывается в начале каждого запроса API, перед его отправкой.

Настройка регистратора

Библиотека ведет минимальное журналирование, но ее можно настроить с помощью регистратора, совместимого с PSR-3 , чтобы сообщения попадали туда вместо error_log :

 Stripe  Stripe :: setLogger ( $ logger );

Доступ к данным ответа

Вы можете получить доступ к данным из последнего ответа API для любого объекта через getLastResponse() .

 $ customer = $ stripe -> customers -> create ([
    ' description ' => ' example customer ' ,
]);
echo $ customer -> getLastResponse ()-> headers [ ' Request-Id ' ];

Проблемы совместимости SSL/TLS

API Stripe теперь требует, чтобы все соединения использовали TLS 1.2. Некоторые системы (особенно некоторые старые версии CentOS и RHEL) способны использовать TLS 1.2, но по умолчанию будут использовать TLS 1.0 или 1.1. В этом случае вы получите invalid_request_error со следующим сообщением об ошибке: «Stripe больше не поддерживает запросы API, сделанные с помощью TLS 1.0. Инициируйте HTTPS-соединения с TLS 1.2 или более поздней версии. Подробнее об этом можно узнать по адресу https://stripe. .com/blog/upgrading-tls.».

Рекомендуемый курс действий — обновить пакеты cURL и OpenSSL, чтобы по умолчанию использовался TLS 1.2, но если это невозможно, вы можете решить проблему, установив для параметра CURLOPT_SSLVERSION значение CURL_SSLVERSION_TLSv1 или CURL_SSLVERSION_TLSv1_2 :

 $ curl = new  Stripe  HttpClient  CurlClient ([ CURLOPT_SSLVERSION => CURL_SSLVERSION_TLSv1 ]);
 Stripe  ApiRequestor :: setHttpClient ( $ curl );

Конфигурация по запросу

Для приложений, которым необходимо использовать несколько ключей в течение жизненного цикла процесса, например приложения, использующего Stripe Connect, также можно установить ключ и/или учетную запись для каждого запроса:

 $ customers = $ stripe -> customers -> all ([],[
    ' api_key ' => ' sk_test_... ' ,
    ' stripe_account ' => ' acct_... '
]);

$ stripe -> customers -> retrieve ( ' cus_123456789 ' , [], [
    ' api_key ' => ' sk_test_... ' ,
    ' stripe_account ' => ' acct_... '
]);

Настройка пакетов CA

По умолчанию библиотека будет использовать собственный внутренний пакет известных сертификатов ЦС, но можно настроить свои собственные:

 Stripe  Stripe :: setCABundlePath ( " path/to/ca/bundle " );

Настройка автоматических повторов

Библиотеку можно настроить на автоматический повтор запросов, которые терпят неудачу из-за периодических проблем с сетью:

 Stripe  Stripe :: setMaxNetworkRetries ( 2 );

Ключи идемпотентности добавляются к запросам, чтобы гарантировать безопасность повторных попыток.

Телеметрия

По умолчанию библиотека отправляет в Stripe телеметрию о задержке запроса и использовании функций. Эти цифры помогают Stripe снизить общую задержку API для всех пользователей и улучшить популярные функции.

Вы можете отключить это поведение, если хотите:

 Stripe  Stripe :: setEnableTelemetry ( false );

Бета-SDK

У Stripe есть функции, находящиеся на стадии бета-тестирования, доступ к которым можно получить через бета-версию этого пакета. Мы будем рады, если вы опробуете их и поделитесь с нами отзывом, прежде чем эти функции выйдут на стабильную фазу. Используйте команду composer require с указанием точной версии, чтобы установить бета-версию пакета Stripe-php.

composer require stripe/stripe-php:v9.2.0-beta.1

Примечание. Между бета-версиями могут быть критические изменения. Поэтому мы рекомендуем привязать версию пакета к конкретной бета-версии в файле композитора.json. Таким образом, вы можете каждый раз устанавливать одну и ту же версию, не нарушая изменений, если только вы намеренно не ищете последнюю бета-версию.

Мы настоятельно рекомендуем следить за тем, когда интересующая вас бета-функция переходит из бета-версии в стабильную, чтобы вы могли перейти от использования бета-версии SDK к стабильной версии.

Если ваша бета-функция требует отправки заголовка Stripe-Version , установите свойство apiVersion объекта config с помощью функции addBetaVersion :

 Stripe :: addBetaVersion ( " feature_beta " , " v3 " );

Индивидуальные запросы

Если вы хотите отправить запрос к недокументированному API (например, вы находитесь в частной бета-версии) или если вы предпочитаете обойти определения методов в библиотеке и указать детали вашего запроса напрямую, вы можете использовать метод rawRequest в StripeClient.

 $ stripe = new  Stripe  StripeClient ( ' sk_test_xyz ' );
$ response = $ stripe -> rawRequest ( ' post ' , ' /v1/beta_endpoint ' , [
  " caveat " : " emptor "
], [
  " stripe_version " => " 2022-11_15 " ,
]);
// $response->body is a string, you can call $stripe->deserialize to get a StripeStripeObject.
$ obj = $ stripe -> deserialize ( $ response -> body );

// For GET requests, the params argument must be null, and you should write the query string explicitly.
$ get_response = $ stripe -> rawRequest ( ' get ' , ' /v1/beta_endpoint?caveat=emptor ' , null , [
  " stripe_version " => " 2022-11_15 " ,
]);

Поддерживать

В последней основной версии библиотеки Stripe PHP выпущены новые функции и исправлены ошибки. Если вы используете более старую основную версию, мы рекомендуем вам выполнить обновление до последней, чтобы использовать новые функции и исправления ошибок, в том числе уязвимостей безопасности. Старые основные версии пакета по-прежнему будут доступны для использования, но не будут получать никаких обновлений.

Разработка

Получите Композитор. Например, в Mac OS:

brew install composer

Установите зависимости:

composer install

Набор тестов зависит от Stripe-mock, поэтому обязательно скачайте и запустите его с фонового терминала (README Stripe-mock также содержит инструкции по установке через Homebrew и другие методы):

go install github.com/stripe/stripe-mock@latest
stripe-mock

Установите зависимости, как указано выше (которые разрешат PHPUnit), затем вы сможете запустить набор тестов:

./vendor/bin/phpunit

Или для запуска отдельного тестового файла:

./vendor/bin/phpunit tests/Stripe/UtilTest.php

Обновите связанные сертификаты CA из версии Mozilla cURL:

./update_certs.php

Библиотека использует PHP CS Fixer для форматирования кода. Код необходимо отформатировать до отправки запросов на запросы, иначе CI не удастся. Запустите форматтер с помощью:

./vendor/bin/php-cs-fixer fix -v . 

Внимание разработчиков плагина

Вы пишете плагин, который интегрирует Stripe и встраивает нашу библиотеку? Затем используйте функцию setAppInfo , чтобы идентифицировать ваш плагин. Например:

 Stripe  Stripe :: setAppInfo ( " MyAwesomePlugin " , " 1.2.34 " , " https://myawesomeplugin.info " );

Метод следует вызывать один раз, прежде чем в API будет отправлен какой-либо запрос. Второй и третий параметры являются необязательными.

Опция конфигурации SSL/TLS

Полный контекст см. в параграфе «Проблемы совместимости SSL/TLS» выше. Если вы хотите, чтобы ваш плагин можно было использовать во всех системах, вам следует добавить параметр конфигурации, позволяющий пользователям выбирать между различными значениями CURLOPT_SSLVERSION : none (по умолчанию), CURL_SSLVERSION_TLSv1 и CURL_SSLVERSION_TLSv1_2 .