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@example.com',
    '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请求的开始时被调用。

配置Logger

库执行最少的日志记录，但它可以使用与PSR-3兼容的logger配置，以便消息最终到达那里而不是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);

测试版SDK

Stripe在测试阶段提供了一些功能，您可以通过此包的测试版本来访问。我们非常希望您尝试这些功能，并在这些功能进入稳定阶段之前与我们分享反馈。使用composer require命令并指定精确版本来安装stripe-php包的测试版。

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。

scarletbeast / stripe-php

维护者

详情