README

A PHP 客户端，用于与 iBanFirst API 交互。

• 指南
• API 参考

安装

安装 ibanfirst-sdk 的推荐方法是使用 Composer。

# Install Composer
curl -sS https://getcomposer.org/installer | php

接下来，运行 Composer 命令来安装 ibanfirst-sdk 的最新稳定版本。

php composer.phar require mradhi/ibanfirst-sdk

安装后，您需要要求 Composer 的自动加载器

require 'vendor/autoload.php';

初始化客户端

创建一个 IBanFirst\IBanFirst 实例，提供您的凭据以及您想要使用的环境。我们强烈建议将凭据存储为环境变量，而不是直接在代码中。您可以通过使用类似 phpdotenv 的工具轻松加载环境变量，但请将其排除在版本控制之外！

$username = getenv('IBANFIRST_USERNAME');
$password = getenv('IBANFIRST_PASSWORD');

$client = new IBanFirst\IBanFirst(array(
    'username'    => $username,
    'password'    => $password,
    'environment' => IBanFirst\IBanFirstEnvironment::SANDBOX
));

环境可以是 IBanFirst\IBanFirstEnvironment::SANDBOX 或 IBanFirst\IBanFirstEnvironment::LIVE，具体取决于您是想使用沙盒还是实时 API。

GET 请求

您可以使用 getList 方法请求获取资源列表。

/**
 * @var IBanFirst\IBanFirst $client
 */
$client->wallets()->getList();

注意：本 README 将使用钱包，但 API 中的每个资源都可在本库中使用。

如果需要传递任何选项，则 getList() 方法中的最后一个参数是选项数组，有关更多信息，请参阅 HttpClient - Query String Parameters，在我们的情况下，如果我们想向 URL 添加一些参数，可以这样操作

/**
 * @var IBanFirst\IBanFirst $client
 */
$wallets = $client->wallets()->getList(['query' => ['page' => 3]]);

getList() 调用返回一个 IBanFirst\Response\ListResponse 实例。您可以使用其 getRecords() 属性遍历结果。

/**
 * @var IBanFirst\Response\ListResponse $wallets
 */
echo count($wallets->getRecords());

/** @var IBanFirst\Resources\Wallet $wallet */
foreach ($wallets->getRecords() as $wallet) {
  echo $wallet->bookingAmount->value;
}

如果需要 URL 参数，方法签名将包含所需参数

/**
 * @var IBanFirst\IBanFirst $client
 */
$wallet = $client->wallets()->getDetails('some_id');
echo $wallet->accountNumber;

与 getList() 类似，最后一个参数可以是选项数组，包含任何 URL 参数

/**
 * @var IBanFirst\IBanFirst $client
 */
$client->wallets()->getDetails('some_id', ['query' => ['some_flag' => true]]);

处理失败

当出现错误时，库将返回一个 IBanFirst\Exception\SDKException 的相应子类之一

• IBanFirst\Exception\AuthenticatorException - 验证器配置无效
• IBanFirst\Exception\ResourceException - 调用给定资源的调用无效
• IBanFirst\Exception\ResponseException - API 返回的错误响应

测试

1. 在 iBanFirst 上创建一个沙盒账户，请参阅 iBanFirst API - 开始
2. 从 tests/config.php.dist 创建 tests/config.php 并编辑它以添加您的凭据。
3. 您可以从根目录运行此命令来执行测试

$ ./vendor/bin/phpunit

默认情况下，测试将向 iBanFirst API 发送实时 HTTP 请求。如果您没有互联网连接，您可以通过排除 client 组来跳过这些测试。

$ ./vendor/bin/phpunit --exclude-group client

观点

• 幕后，此库使用 HttpClient 组件与 iBanFirst API 通信，但您可以使用自己的 HttpClient，它应该实现 Symfony\Contracts\HttpClient\HttpClientInterface，然后您可以使用以下方式配置 IBanFirst\IBanFirst 对象

/**
* @var Symfony\Contracts\HttpClient\HttpClientInterface $customClient
*/
$client = new IBanFirst\IBanFirst(array(
   // ... the required options here
   'http_client' => $customClient
));

有关此主题的更多信息，请参阅 HttpClient - HttpPlug 文档

• 目前，该库仅支持一种身份验证方法 IBanFirst\Authenticator\UsernameTokenAuthenticator，但其设计允许我们通过仅实现接口 IBanFirst\Authenticator\AuthenticatorInterface 来轻松添加更多身份验证器。

• 目前，该库仅支持两种API服务

  • IBanFirst\Service\WalletsService - 用于与 /wallets/ 端点交互的服务。
  • IBanFirst\Service\FinancialMovementsService - 用于与 /financialMovements/ 端点交互的服务。

我们可以轻松地向此包装器添加更多服务，每个服务应扩展 IBanFirst\Service\AbstractService 类，并且每个公共方法调用的返回值应为 IBanFirst\Response\ListResponse 或 IBanFirst\Resources\AbstractResource 的实例，这有助于确保良好的类型提示。

支持 PHP >= 7.4

此客户端库仅支持最新版本的 PHP >= 7.4，有关更多信息，请检查 支持的版本。