README

UnivaPay PHP SDK 提供了与 UnivaPay 支付网关配合使用的一系列便捷方法。

所需条件

PHP 7.2.x 以上
Composer
npm (仅限开发)
UnivaPay 的商店应用程序令牌或商户应用程序令牌

安装

composer require univapay/php-sdk

使用方法

use Univapay\UnivapayClient;
use Univapay\UnivapayClientOptions;
use Univapay\Requests\Handlers\RateLimitHandler;

$client = new UnivapayClient(AppJWT::createToken('token', 'secret'));

// その他のオプションは、クライアントをインスタンス化する前にクライアントオプションオブジェクトを作成および変更します
// すべてのオプションについては、UnivapayClientOptionsを参照してください
$clientOptions = new UnivapayClientOptions();
$clientOptions->rateLimitHandler = new RateLimitHandler(5, 2);
$client = new UnivapayClient(AppJWT::createToken('token', 'secret'), $clientOptions);

// 使用例については、examplesフォルダを参照してください

应用程序令牌

此 SDK 支持商店类型和商户类型的应用程序令牌。除了需要商店类型令牌的交易令牌或收费创建之外的所有功能都支持两种令牌类型。

货币模型

此 SDK 使用 moneyphp 库来建模金额和货币。详细信息请参阅文档。

所有货币和金额都将自动转换为 Currency 和 Money 对象。格式化的金额（由 .*Formatted 键表示）仅以字符串形式存在。

use Money\Currency;
use Money\Money;
use Univapay\PaymentMethod\CardPayment;

$paymentMethod = new CardPayment(...);
$charge = $client
    ->createToken($paymentMethod)
    ->createCharge(Money::USD(1000));

$charge->currency === new Currency('USD'); // true
$charge->requestAmount === new Money(1000, $charge->currency); // true

枚举类型

PHP 没有内置的枚举类型支持，因此为了在操作枚举值时提供类型安全性，提供了一个名为 TypedEnum 的类。每个枚举子类都是最终的，并通过扩展 TypedEnum 提供了类似于 Java 等其他语言的枚举子类的静态函数。枚举类型类位于 Univapay\Enums 命名空间中。

默认情况下，如果创建时未指定值，则使用蛇形命名法。

use Univapay\Enums\ChargeStatus;

$values = ChargeStatus::findValues(); // 列挙子のすべての名前と値のリストを取得する
$chargeStatus = ChargeStatus::PENDING(); // 最後のカッコに注意してください
$chargeStatus->getValue() === 'pending'; // true
$chargeStatus === ChargeStatus::fromValue('pending'); // true
// switchステートメントでも機能します
switch ($chargeStatus) {
    case ChargeStatus::PENDING():
        // Do something
        break;
    // ...
}

资源模型的更新

要更新资源模型（扩展 Resource 的模型类），请按以下方式操作。

$charge->fetch();

轮询

以下资源支持用于等待状态更改的长轮询。

收费
退款
取消
订阅

这些请求最初返回 PENDING 状态。在长轮询中，当资源状态更改时，可以获取更新后的模型。如果在 3 秒内没有变化，则返回当前资源。作为选项，可以传递重试次数，以便在返回 PENDING 状态时自动重试。

$charge = $client
    ->createCharge($token->id, Money::USD(1000)) // $charge->status == PENDING
    ->awaitResult(); // $charge->status == SUCCESSFUL
    
// OR
$charge = $client
    ->createCharge($token->id, Money::USD(1000)) // $charge->status == PENDING
    ->awaitResult(5); // `PENDING`以外ステータスを返すまで、5回まで（最大15秒）をリトライを実行

列表和分页

SDK 的所有列表函数都按创建日期降序以 Paginated 对象的形式返回。传递参数时，请注意输入应与期望的类型一致。如果不一致，将抛出 InvalidArgumentException。

use InvalidArgumentException;
use Univapay\Enums\CursorDirection;

try {
    $transactionList = $client->listTransactionsByOptions([
        'from' => date_create('-1 week'),
        'to' => date_create('+1 week')
    ]);
} catch (InvalidArgumentException $error) {
    // 入力パラメーターが正しいタイプに対応していない場合
}

$transactions = $transactionList->items; // 1ページあたりのデフォルトの上限 = 10アイテム

if ($transactionList->hasMore) {
    $transactionList = $transactionList->getNext(); // リストは内部で変化しない
    $transactions = array_merge($transactions, $transactionList->items);
}

$firstTenItems = $client->listTransactionsByOptions([
    'from' => date_create('-1 week'),
    'to' => date_create('+1 week'),
    'cursor_direction' => CursorDirection::ASC()
]);

请求/响应处理程序

这是一个在解析数据对象之前进行额外更改或对响应做出反应的示例。 SDK 提供了一个名为 RateLimitHandler 的请求调整器，该请求调整器基于来自 API 的背压（这是默认在 UnivapayClientOptions-> rateLimitHandler 中实现的）。此外，还提供了一个名为 BasicRetryHandler 的处理程序，它可以捕获特定异常并进行过滤以进行重试。要指定要捕获的异常，请：

use Univapay\Requests\Handlers\BasicRetryHandler;

$subscriptionTokenRetryHandler = new BasicRetryHandler(
    UnivapayResourceConflictError::class,
    5, // 5回トライする
    2, // 2秒毎
    // エラーに基づいたより具体的なフィルタリングは、最初のパラメーターからエラー内容を取得してください
    // 再試行する場合はtrueを、無視する場合はfalseを返します
    function (UnivapayResourceConflictError $error) {
        return $error->code === 'NON_UNIQUE_ACTIVE_TOKEN';
    }
);
$client->addHandlers($subscriptionTokenRetryHandler);

// 新しいハンドラーをリセットするか、クリアして最初から追加する
// rateLimitHandlerはUnivapayClientOptionsから自動的に追加されます
$client->setHandlers($subscriptionTokenRetryHandler);

SDK 开发者指南

构建

composer install
npm install

# 必要に応じて
npm install -g grunt

代码格式

grunt phpcs

测试

要运行测试，需要以下环境变量。

UNIVAPAY_PHP_TEST_TOKEN - test 模式的令牌
UNIVAPAY_PHP_TEST_SECRET
UNIVAPAY_PHP_TEST_ENDPOINT - 指向本地 API 实例或阶段实例

grunt phpunit

注意：GitHub Actions 仅在 Opened 分支的拉取请求上执行

univapay / php-sdk

维护者

详细信息