README

PHP XRPL API 连接器

要求

PHP 8.1 或更高版本
Composer

安装

composer require xrplwin/xrpl

使用示例

在以下示例中，我们将使用 account_tx 方法。

初始化客户端

$client = new \XRPLWin\XRPL\Client([
    # Following values are defined by default, uncomment to override
    //'endpoint_reporting_uri' => 'http://s1.ripple.com:51234',
    //'endpoint_fullhistory_uri' => 'https://xrplcluster.com'
]);

创建第一个请求

# Create new 'account_tx' method instance
$account_tx = $client->api('account_tx')->params([
    'account' => 'rAccount...',
    'limit' => 10
]);

这将返回一个 XRPLWin\XRPL\Api\Methods\AccountTx 实例。

自定义速率限制处理

如果您想通过 Closure 函数定义当请求被速率限制时的自定义行为，可以在执行 send() 之前定义它。

//(optional) Override default cooldown seconds (default is 5 seconds)
$account_tx->setCooldownSeconds(10);
//(optional) Override default number of tries when request is rate-limited (default is 3)
$account_tx->setTries(5);
//(optional) Set http timeout to 3 seconds (default is 0 - eg no timeout)
//           After 3 seconds method will throw \XRPLWin\XRPL\Exceptions\BadRequestException on timeout
$account_tx->setTimeout(3);

//(optional) Define custom cooldown callback
$account_tx->setCooldownHandler(
    /**
     * @param int $current_try Current try 1 to max
     * @param int $default_cooldown_seconds Predefined cooldown seconds
     * @return void|boolean return false to stop process
     */
    function(int $current_try, int $default_cooldown_seconds) {
        //Sample usage: calculate how much sleep() is needed depending on 
        $sec = $default_cooldown_seconds * $current_try;
        if($sec > 15) return false; //force stop
        sleep($sec);
    }
);

获取响应

# Send request to Ledger
try {
    $account_tx->send();
} catch (\XRPLWin\XRPL\Exceptions\XWException $e) {
    // Handle errors
    throw $e;
}

if(!$account_tx->isSuccess()) {
    //XRPL response is returned but field result.status did not return 'success'
}

# Get fetched response as array
$response       = $account_tx->resultArray(); //array response from ledger
# Get fetched response as object
$response       = $account_tx->result();      //object response from ledger
# Get fetched final result from helper (varies method to method)
$transactions   = $account_tx->finalResult(); //array of transactions

类方法 send() 对 XRPLedger 执行请求，并将响应存储到实例对象中。之后，您可以使用提供的类方法之一来检索结果。

承诺

作为上面定义的同步响应的替代方案，您可以通过获取 Promise
了解更多关于承诺的信息。返回的对象是 Promises/A+ 实现。

$promise = $account_tx->requestAsync();

$promises = [
    'rAcct1' => $promise,
    //...more promises
];

// Wait for the requests to complete
// Throws a ConnectException if any of the requests fail
$responses = \GuzzleHttp\Promise\Utils::unwrap($promises);

//Fill response data back into $account_tx instance
$account_tx->fill($responses['rAcct1']);

//...
$transactions = $account_tx->finalResult();

注意：使用承诺时，您需要自己处理速率限制和异常处理。另外，每个承诺都必须由新的 \XRPLWin\XRPL\Client 实例创建，这是为了确保每个承诺都有自己的单独的 HttpClient 实例。

分页结果

# Check if there is next page
//$has_next_page = $account_tx->hasNextPage(); //bool

# Fetch next page of transactions if there is next page (next() does not return null)
if($next_account_tx = $account_tx->next()) {
    $next_result = $next_account_tx->send()->finalResult();
    // ...
}

要快速检索下一个要执行的实例（下一页），您可以使用 next()。此类方法将返回具有相同参数并添加了先前请求标记的 XRPLWin\XRPL\Api\Methods\AccountTx 实例。此辅助函数不是强制的，您始终可以手动创建新的方法实例，例如 $client->api('account_tx')->params([ ..., ['marker'] => [ ... ]]。

有关更多信息，请参阅示例。

请求流程

通过设置参数准备实例
使用 send() 执行请求，并通过 try catch 处理错误。（如果检测到速率限制，请求将重试 x 次）
XRPLedger 响应存储在内存中，并通过以下方式可供读取：
->result()
->resultArray()
->finalResult()

方法

account_tx

$account_tx = $client->api('account_tx')->params([
    'account' => 'rAccount...',
    'limit' => 10
]);

tx

$account_tx = $client->api('tx')->params([
    'transaction' => 'DE80B0064677CEFFDE...',
    'binary' => false
]);

有关其他方法的详细信息，请参阅 https://xrpl.org/websocket-api-tool.html 和 src/Api/Methods

实用工具

此包提供了一些实用工具

余额变动（可选带有交易费用计算）
标志
UNLReport 标志账本
货币代码转换为可读货币代码

标志

use XRPLWin\XRPL\Utilities\Flags;

//Methods:
Flags::extract(int $flags, string $transactionType): array
Flags::description(string $transactiontype, string $flagname, bool $htmlFormat = false): string
Flags::hasFlag(int $flags, int $check): bool

UNLReportFlagLedger

标志账本使用模公式 LedgerIndex % 256 计算。

use XRPLWin\XRPL\Utilities\UNLReportFlagLedger;

UNLReportFlagLedger::isFlag(256);   //for ledger sequence 256 - true
UNLReportFlagLedger::isFlag(257);   //for ledger sequence 257 - false
UNLReportFlagLedger::prev(6873600);          //6873344
UNLReportFlagLedger::prevOrCurrent(6873600); //6873600
UNLReportFlagLedger::next(6873600);          //6873856
UNLReportFlagLedger::nextOrCurrent(6873600); //6873600

Util 类

将 ISO 或十六进制货币代码转换为可读表示。

use XRPLWin\XRPL\Utilities\Util;
#Syntax: Util::currencyToSymbol(string $ISO_or_HEX, $malformedUtf8ReturnString = '?')

//ISO Currency Code
Util::currencyToSymbol('EUR') //EUR 
//Deprecated Demurrage Currency Code
Util::currencyToSymbol('0158415500000000C1F76FF6ECB0BAC600000000') //XAU (-0.5% pa)
//Nonstandard Currency Code
Util::currencyToSymbol('534F4C4F00000000000000000000000000000000') //SOLO

运行测试

在 "tests" 目录中运行所有测试。

composer test

或

./vendor/bin/phpunit --testdox

xrplwin / xrpl

维护者

详细信息