README

Stripe PHP 库提供了从 PHP 语言编写的应用程序中方便地访问 Stripe API 的方法。它包括一组预定义的类，用于初始化 API 资源，这些类可以从 API 响应中动态初始化，这使得它与 Stripe API 的多种版本兼容。

要求

PHP 5.6.0 及以上版本。

Composer

您可以通过 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@example.com',
    'payment_method' => 'pm_card_visa',
]);
echo $customer;

客户端/服务模式与旧模式

您可以使用在版本 7.33.0 之前使用的旧集成模式。请参阅迁移指南了解向后兼容客户端/服务模式的变化。

文档

请参阅 PHP API 文档。

旧版本支持

PHP 5.4 & 5.5

如果您正在使用 PHP 5.4 或 5.5，可以从我们的发布页面下载 v6.21.1（zip，tar.gz）。此版本将继续与 Stripe API 的新版本在所有常见用途上工作。

PHP 5.3

如果您正在使用 PHP 5.3，可以从我们的发布页面下载 v5.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 \Stripe\HttpClient\CurlClient::DEFAULT_TIMEOUT
$curl->setConnectTimeout(5); // default is \Stripe\HttpClient\CurlClient::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() 相同的语法。这将设置 SDK 每次HTTP请求的默认 cURL 选项，尽管即使在此处设置，许多更常见的选项（例如超时；参见上方如何设置它们）也将被客户端覆盖。

// 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 构造函数，该函数根据请求输入返回上述数组。参见 tests/CurlClientTest.php 中的 testDefaultOptions() 以获取此行为的示例。请注意，可调用的函数在每个 API 请求开始时被调用，在请求发送之前。

配置日志记录器

库执行了最少的日志记录，但可以配置为使用与 PSR-3 兼容的日志记录器，以便消息最终出现在那里而不是 error_log。

\Stripe\Stripe::setLogger($logger);

访问响应数据

您可以通过 getLastResponse() 在任何对象上访问最后一次 API 响应中的数据。

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

SSL / TLS 兼容性问题

Stripe 的 API 现在要求所有连接都使用 TLS 1.2。一些系统（特别是某些较旧的 CentOS 和 RHEL 版本）能够使用 TLS 1.2，但默认情况下将使用 TLS 1.0 或 1.1。在这种情况下，您将收到一个带有以下错误消息的 invalid_request_error：“Stripe 不再支持使用 TLS 1.0 发送的 API 请求。请使用 TLS 1.2 或更高版本的 HTTPS 连接。您可以在 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 套件

默认情况下，库将使用其自己的已知 CA 证书内部套件，但也可以配置您自己的套件。

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

配置自动重试

库可以配置为自动重试因间歇性网络问题而失败的请求。

\Stripe\Stripe::setMaxNetworkRetries(2);

在请求中添加幂等性键，以确保重试是安全的。

请求延迟遥测

默认情况下，库会将请求延迟遥测发送到 Stripe。这些数字有助于 Stripe 提高其 API 的整体延迟。

如果您愿意，可以禁用此行为。

\Stripe\Stripe::setEnableTelemetry(false);

开发

获取 Composer。例如，在 Mac OS 上

brew install composer

安装依赖项

composer install

测试套件依赖于 stripe-mock，因此请确保从后台终端获取并运行它（stripe-mock 的 README 还包含通过 Homebrew 和其他方法安装的说明）

go get -u github.com/stripe/stripe-mock
stripe-mock

如上所述安装依赖项（这将解决 PHPUnit），然后您可以运行测试套件

./vendor/bin/phpunit

或者运行单个测试文件

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

从 Mozilla cURL 发布更新捆绑的 CA 证书

./update_certs.php

该库使用PHP CS Fixer进行代码格式化。在提交PR之前，代码必须格式化，否则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值：无（默认），CURL_SSLVERSION_TLSv1和CURL_SSLVERSION_TLSv1_2。

shubhamdhaboya / stripe-php

维护者

详情