README

The Payske PHP library provides convenient access to the Payske API from applications written in the PHP language. It includes a pre-defined set of classes for API resources that initialize themselves dynamically from API responses which makes it compatible with a wide range of versions of the Payske API.

要求

PHP 5.6.0 及更高版本。

Composer

You can install the bindings via Composer. Run the following command

composer require payske-dev/payske-php

To use the bindings, use Composer's autoload

require_once('vendor/autoload.php');

手动安装

If you do not wish to use Composer, you can download the latest release. Then, to use the bindings, include the init.php file.

require_once('/path/to/Payske-php/init.php');

依赖

The bindings require the following extensions in order to work properly

curl, although you can use your own non-cURL client if you prefer
json
mbstring (多字节字符串)

If you use Composer, these dependencies should be handled automatically. If you install manually, you'll want to make sure that these extensions are available.

入门指南

简单用法如下

$Payske = new \Payske\PayskeClient('sk_test_BQokikJOvBiI2HlWgH4olfQ2');
$customer = $Payske->customers->create([
    'description' => 'example customer',
    'email' => 'email@example.com',
    'payment_method' => 'pm_card_visa',
]);
echo $customer;

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

You can continue to use the legacy integration patterns used prior to version 7.33.0. Review the migration guide for the backwards-compatible client/services pattern changes.

文档

查看 PHP API 文档.

查看视频演示了解如何使用该库。

旧版本支持

PHP 5.4 & 5.5

If you are using PHP 5.4 or 5.5, you should consider upgrading your environment as those versions have been past end of life since September 2015 and July 2016 respectively. Otherwise, you can still use Payske by downloading Payske-php v6.43.1 (zip, tar.gz) from our releases page. This version will work but might not support recent features we added since the version was released and upgrading PHP is the best course of action.

PHP 5.3

If you are using PHP 5.3, you should upgrade your environment as this version has been past end of life since August 2014. Otherwise, you can download v5.9.2 (zip, tar.gz) from our releases page. This version will continue to work with new versions of the Payske API for all common uses.

自定义请求超时

注意：我们不建议减少非只读调用（例如创建充电）的超时时间，因为即使您本地超时，Payske侧的请求仍然可以完成。如果您正在减少这些调用中的超时时间，请确保使用幂等令牌来避免因超时重试逻辑而执行相同的交易两次。

要修改请求超时（连接或总时间，单位为秒），您需要告诉API客户端使用除默认以外的CurlClient。您将在那个CurlClient中设置超时。

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

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

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

// use the Payske API client as you normally would

自定义cURL选项（例如代理）

需要为请求设置代理？将必需的CURLOPT_*数组传递给CurlClient构造函数，使用与curl_stopt_array()相同的语法。这将设置SDK每个HTTP请求的默认cURL选项，尽管即使在此处设置，许多更常见的选项（例如超时；见上文如何设置这些）也将被客户端覆盖。

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

或者，可以将一个可调用的对象传递给CurlClient构造函数，该对象根据请求输入返回上述数组。参见tests/CurlClientTest.php中的testDefaultOptions()示例。请注意，在请求发送之前，每次API请求的开始都会调用该可调用对象。

配置记录器

该库执行最小化日志记录，但它可以使用PSR-3兼容的记录器进行配置，以便消息最终出现在那里而不是error_log

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

访问响应数据

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

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

SSL / TLS兼容性问题

Payske的API现在要求所有连接使用TLS 1.2。一些系统（特别是某些较旧的CentOS和RHEL版本）能够使用TLS 1.2，但默认情况下会使用TLS 1.0或1.1。在这种情况下，您将收到一个invalid_request_error错误，错误消息如下：“Payske不再支持使用TLS 1.0制作的API请求。请使用TLS 1.2或更高版本的HTTPS连接。您可以在https://payske.com/blog/upgrading-tls上了解更多信息。”。

建议的操作是升级您的cURL和OpenSSL包，以便默认使用TLS 1.2，但如果这不可能，您可能可以通过将CURLOPT_SSLVERSION选项设置为CURL_SSLVERSION_TLSv1或CURL_SSLVERSION_TLSv1_2来解决此问题。

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

按请求配置

对于需要在进程生命周期内使用多个密钥的应用程序，例如使用Payske Connect的应用程序，也可以设置每个请求的密钥和/或账户

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

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

配置CA捆绑包

默认情况下，该库将使用自己的内部已知CA证书捆绑包，但您可以配置自己的捆绑包

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

配置自动重试

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

\Payske\Payske::setMaxNetworkRetries(2);

幂等性键被添加到请求中，以保证重试是安全的。

请求延迟遥测

默认情况下，该库将向Payske发送请求延迟遥测。这些数字有助于Payske提高其API对所有用户的整体延迟。

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

\Payske\Payske::setEnableTelemetry(false);

开发

获取Composer。例如，在Mac OS上

brew install composer

安装依赖项

composer install

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

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

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

./vendor/bin/phpunit

或者运行单个测试文件

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

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

./update_certs.php

该库使用 PHP CS Fixer 进行代码格式化。在提交 PR 之前，代码必须格式化，否则 CI 将失败。使用以下命令运行格式化程序

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

注意插件开发者

您正在编写一个集成了 Payske 并嵌入我们库的插件吗？那么请使用 setAppInfo 函数来标识您的插件。例如

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

该方法应该在发送任何请求到 API 之前调用一次。第二个和第三个参数是可选的。

SSL / TLS 配置选项

请参阅上面的“SSL / TLS 兼容性问题”段落以了解完整上下文。如果您想确保您的插件可以在所有系统上使用，您应该添加一个配置选项，让用户可以选择 CURLOPT_SSLVERSION 的不同值：无（默认），CURL_SSLVERSION_TLSv1 和 CURL_SSLVERSION_TLSv1_2。

payske-dev / payske-php

维护者

详细信息