README

Currencycloud API v2 PHP客户端

版本：3.9.0

这是Currencycloud API的官方PHP SDK。每个API端点的额外文档可以在developer.currencycloud.com找到。

如果您有任何疑问或需要支持，请联系我们的开发团队development@currencycloud.com。请在任何通信中引用您的登录ID，这将使我们更容易找到您的账户并提供所需的支持。

先决条件

Composer（可选，但强烈推荐）

CurrencyCloud-PHP是一个Composer项目。虽然使用Composer不是强制性的，但使用Composer来处理依赖管理和自动加载会更加方便。

支持的PHP版本

此库旨在支持并已针对PHP 7.4和PHP 8.0进行测试。

安装

推荐通过Composer安装Currencycloud SDK。

如果您尚未安装Composer，请参阅Composer安装指南。

假设您已全局安装Composer，您可以通过执行以下操作将Currencycloud SDK添加到项目中

composer require currency-cloud/client

安装后，如果您之前没有要求，您需要要求Composer的自动加载器

require 'vendor/autoload.php';

用法

您可以在developer.currencycloud.com注册示例API密钥。

PHP 7的示例

use CurrencyCloud\CurrencyCloud;
use CurrencyCloud\Session;

require_once __DIR__ . '/vendor/autoload.php';

$session = new Session(
    Session::ENVIRONMENT_DEMONSTRATION,
    '<user-id>',
    '<api-key>'
);

$client = CurrencyCloud::createDefault($session);

//Authenticate
$client->authenticate()
    ->login();

//Get available currencies
$currencies =
    $client->reference()
        ->availableCurrencies();

echo "Supported currencies:\n";

foreach ($currencies as $currency) {
    printf(
        "Currency: %s; Code: %s; Decimal places: %d\n",
        $currency->getName(),
        $currency->getCode(),
        $currency->getDecimalPlaces()
    );
}

echo "Balances:\n";

//Find balances
$balances =
    $client->balances()
        ->find();

foreach ($balances->getBalances() as $balance) {
    printf(
        "Balance ID: %s; Currency: %s; Amount: %s\n",
        $balance->getId(),
        $balance->getCurrency(),
        $balance->getAmount()
    );
}

//Close session
$client->authenticate()->close();

对于更长的示例，请参阅cook-book.php，它是对文档中食谱的实现。

常见模式

在多个请求中重用客户端

身份验证令牌是长期有效的，并且旨在用于多个请求。这将提高通过API的调用性能。

代表

如果您想代表其他用户进行调用（例如，您的最终客户），您可以通过用户的联系ID执行某些“代表”用户的命令。以下是一个示例

$client->onBehalfOf('c6ece846-6df1-461d-acaa-b42a6aa74045', function (CurrencyCloud $client) {
    $balances =
        $client->balances()
            ->find();

    foreach ($balances->getBalances() as $balance) {
        printf(
            "Balance ID: %s; Currency: %s; Amount: %s\n",
            $balance->getId(),
            $balance->getCurrency(),
            $balance->getAmount()
        );
    }
});

上述每笔交易都将在该联系范围的限制内执行，并关联到该联系。请注意，执行交易的真实用户也将被存储。

错误

当API出现错误时，库旨在提供尽可能多的信息。将抛出一个包含许多有用信息的CurrencyCloudException，您可以通过其方法访问这些信息。当异常转换为字符串时，它将提供如下信息

BadRequestException
---
platform: 'PHP 7.1.11-1+deb.sury.org~trusty+1'
request:
    parameters: {  }
    verb: get
    url: 'https://devapi.currencycloud.com/v2/rates/detailed?buy_currency=EUR&sell_currency=GBP&fixed_side=buy&amount=10000.00'
response:
    status_code: 400
    date: 'Tue, 13 Nov 2018 13:40:00 GMT'
    request_id: '2915002181730358306'
errors:
    -
        field: base
        code: rate_could_not_be_retrieved
        message: 'Rate could not be retrieved'
        params: {  }

这分为5个部分

错误类型：在这种情况下，BadRequestException代表HTTP 400错误
平台：客户端中使用的PHP实现
请求：有关已发出的HTTP请求的详细信息，例如POST参数
响应：有关返回的HTTP响应的详细信息，例如HTTP状态码
错误：提供额外信息的错误列表

最后一部分包含有价值的信息

字段：与错误相关的参数
代码：表示此错误的代码
消息：解释错误的可读性消息
参数：包含错误消息动态部分的映射，用于构建自定义错误消息

当与Currencycloud支持团队合作解决API调用问题时，在所有通信中包含完整的错误信息可能非常有帮助。

开发

测试

可以使用vendor/bin/phpunit运行测试用例。

依赖

贡献

我们欢迎所有人的pull请求！ 请参阅 CONTRIBUTING。对我们创建世界上最好的货币移动API的巨大帮助，我们表示衷心的感谢！

版本控制

本项目使用语义版本控制。您可以安全地表达对主版本的依赖，并期望所有次要和修补程序版本都与之前兼容。

弃用策略

技术发展迅速，我们一直在寻找更好的方式来服务我们的客户。有时我们需要通过移除不再必要的代码部分来为创新腾出空间。我们理解这可能会造成干扰，因此我们设计了一项弃用策略，以保护客户的投资，并使我们能够利用现代工具、框架和实践来开发软件。

弃用意味着我们不鼓励使用功能、设计或实践，因为它们已被取代或不再被认为是高效或安全的，但我们不是立即将其删除，而是将其标记为 @deprecated 以提供向后兼容性和时间来更新您的项目。在弃用的功能在SDK中保留一段时间期间，我们建议您将其替换为代码相关部分中解释的推荐替代方案。

我们从宣布之日起三个月后移除弃用的功能。

我们客户资产的安全对我们至关重要，有时我们不得不弃用功能，因为它们可能构成安全威胁，或者因为有更安全的新方法。在这种情况下，我们保留设定不同弃用期的权利，该期可能从 立即删除 到标准的 三个月。

一旦功能被标记为弃用，我们就不再开发代码或实施错误修复。我们只做安全修复。

弃用功能列表

(No features are currently being deprecated)

支持

我们积极支持SDK的最新版本。我们基于最佳努力支持立即先前的版本。所有其他版本不再受支持或维护。

版权

版权（c）2015-2021 Currencycloud。有关详细信息，请参阅 LICENSE。

currency-cloud / client

维护者

详细信息