README

Stripe PHP 库提供了方便的从用 PHP 编写的应用程序中访问 Stripe 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 protected]',
    'payment_method' => 'pm_card_visa',
]);
echo $customer;

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

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

文档

请参阅 PHP API 文档。

请参阅 视频演示，了解如何使用库。

旧版本支持

PHP 5.4 & 5.5

如果您正在使用 PHP 5.4 或 5.5，您应该考虑升级您的环境，因为这些版本分别已于 2015 年 9 月和 2016 年 7 月停止支持。否则，您仍然可以通过从我们的 发布页面 下载 stripe-php v6.43.1（zip，tar.gz）来使用 Stripe。此版本将正常工作，但可能不支持自发布以来添加的某些新功能，升级 PHP 是最佳行动方案。

PHP 5.3

如果您正在使用 PHP 5.3，您应该升级您的环境，因为这个版本已于 2014 年 8 月停止支持。否则，您可以从我们的 发布页面 下载 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);

beta SDK

Stripe有一些处于beta阶段的功能，可以通过此包的beta版本访问。我们希望您尝试这些功能，并在这些功能达到稳定阶段之前与我们分享反馈。使用带有指定版本的composer require命令安装stripe-php包的beta版本。

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

注意 在不同测试版之间可能会有破坏性更改。因此，我们建议在您的 composer.json 文件中将包版本锁定到特定的测试版。这样，您每次都可以安装相同的版本，除非您有意寻找最新的测试版。

我们强烈建议您关注您感兴趣的测试版功能何时从测试版转为稳定版，这样您就可以从使用 SDK 的测试版迁移到稳定版。

如果您的测试版功能需要发送 Stripe-Version 标头，请使用函数 addBetaVersion 设置 config 对象的 apiVersion 属性。

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

支持

新功能和错误修复会在 Stripe PHP 库的最新主要版本上发布。如果您使用的是旧版本，我们建议您升级到最新版本，以使用新功能和错误修复，包括安全漏洞的修复。旧版本的主要版本将继续可用，但将不会接收任何更新。

开发

获取 Composer。例如，在 Mac OS 上

brew install composer

安装依赖项

composer install

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

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

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

./vendor/bin/phpunit

或运行单个测试文件

./vendor/bin/phpunit tests/Stripe/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。