README

Extraton，PHP TON Client

Extraton 是一个简单且强大的 php-library，用于绑定到 TON SDK。它允许与 FreeTON 区块链交互。它具有丰富的功能

实现了 TON SDK v1.0.0 的所有方法
通过异步调用来与 TON SDK 交互
每个方法都包含内联文档
在类似 PHPStorm 的 IDE 中提供完整的自动补全功能
通过 Composer 软件包管理器简单安装
自动下载当前环境的 TON SDK 库
客户端自动配置（开箱即用）
由单元测试覆盖
完全由集成测试覆盖
维护代码质量的工具（静态分析器和编码风格检查器）
快速开发的工具（请参阅 Dockerfile + Makefile）
通过通用异常接口进行错误处理（请参阅 src/Exception）
使用生成器迭代异步事件
您可以根据 FFIAdapter 和 Binding 添加自己的客户端实现
简单的 GraphQL 请求接口
为集成测试运行创建临时日志，以便进行详细分析

要求

php7.4+ 或 php8.0+
ffi 扩展
json 扩展
zlib 扩展
TON SDK 库 1.21.5（包含下载脚本）

安装

要使用 Composer 安装，只需在项目根目录中运行

composer require extraton/php-ton-client

要自动下载 TON SDK 库，请将以下行添加到您的项目 composer.json 文件中

...
  "scripts": {
    "download-ton-sdk-library": "Extraton\\TonClient\\Composer\\Scripts::downloadLibrary",
    "post-update-cmd": [
      "@download-ton-sdk-library"
    ],
    "post-install-cmd": [
      "@download-ton-sdk-library"
    ]
  }
...

在您的项目根目录中调用 composer install 或 composer update 命令后，将下载库。要强制下载适用于您的操作系统的 TON SDK 库，请运行以下命令

composer run download-ton-sdk-library

TON SDK 库将安装到目录 YOUR_PROJECT_ROOT/vendor/extranton/php-ton-client/bin/。

配置

简单的 TonClient 实例化

$tonClient = TonClient::createDefault();

它使用默认配置

$config = [
    "network" => [
        'server_address'             => 'net.ton.dev',
        'network_retries_count'      => 5,
        'message_retries_count'      => 5,
        'message_processing_timeout' => 60000,
        'wait_for_timeout'           => 60000,
        'out_of_sync_threshold'      => 30000,
        'access_key'                 => ''
    ],
    'abi'     => [
        'workchain'                              => 0,
        'message_expiration_timeout'             => 60000,
        'message_expiration_timeout_grow_factor' => 1.35
    ],
    'crypto'  => [
        'mnemonic_dictionary'   => 1,
        'mnemonic_word_count'   => 12,
        'hdkey_derivation_path' => "m/44'/396'/0'/0/0",
        'hdkey_compliant'       => true
    ],
];

您可以使用简单的配置开始使用 TonClient

$config = [
    'network' => [
        'server_address' => 'net.ton.dev'
    ]
];

所有配置选项均在此处提供 here。实例化 TonClient 后，将自动检测操作系统和 TON SDK 库的路径

// Create new instance with custom configuration and default path to TON SDK library
$tonClient = new TonClient($config);

默认路径：YOUR_PROJECT_ROOT/vendor/extraton/bin/tonclient.*。您还可以通过以下代码行指定路径

// Create new instance TonClient with custom path to TON SDK library
$binding = new Binding('PATH_TO_TON_SDK_LIBRARY');
$tonClient = new TonClient($config, $binding);

基本用法

// Get TON SDK version
$result = $tonClient->version();

echo "TON SDK version: " , $result->getVersion() . PHP_EOL;

// Get instance of Crypto module
$crypto = $tonClient->getCrypto();

// Generate random key pair
$result = $crypto->generateRandomSignKeys();
$keyPair = $result->getKeyPair();

echo 'Public key: ' . $keyPair->getPublic() . PHP_EOL;
echo 'Private key: ' . $keyPair->getSecret() . PHP_EOL;

// Get instance of Utils module
$utils = $tonClient->getUtils();

// Convert address to hex format
$result = $utils->convertAddressToHex('ee65d170830136253ad8bd2116a28fcbd4ac462c6f222f49a1505d2fa7f7f528');

echo 'Hex: ' . $result->getAddress() . PHP_EOL;

构建查询

使用特殊类轻松构建查询

$query = (new ParamsOfWaitForCollection('accounts'))
   ->addResultField('id', 'last_paid')
   ->addFilter('last_paid', Filters::IN, [1601332024, 1601331924])
   ->setTimeout(60_000);

$net->waitForCollection($query);

$query = (new ParamsOfSubscribeCollection('transactions'))
    ->addResultField('id', 'block_id', 'balance_delta')
    ->addFilter('balance_delta', Filters::GT, '0x5f5e100');
    
$net->subscribeCollection($query);

$query = new ParamsOfQueryCollection('accounts');
$query->addResultField(
    'acc_type',
    'acc_type_name',
    'balance',
    'boc',
    'id',
    'last_paid',
    'workchain_id',
);
$query->addFilter(
    'last_paid',
    Filters::IN,
    [
        1601332024,
        1601331924,
        1601332491,
        1601332679
    ]
);
$query->addOrderBy('last_paid', OrderBy::DESC)->setLimit(2);

$net->queryCollection($query);

您可以根据 \Extraton\TonClient\Entity\Net\QueryInterface 接口实现或扩展 \Extraton\TonClient\Entity\Net\AbstractQuery 类来添加自己的查询类。

以下是一些可用于过滤器和方向的常量：

class Filters implements Params
{
    public const EQ = 'eq';
    public const GE = 'ge';
    public const GT = 'gt';
    public const IN = 'in';
    public const LE = 'le';
    public const LT = 'lt';
    public const NE = 'ne';
    public const NOT_IN = 'notIn';
...

class OrderBy implements Params
{
    public const ASC = 'ASC';
    public const DESC = 'DESC';
...

高级用法

使用以下示例构建一个用于监控来自区块链网络的事件的程序：

// Build query
$query = (new ParamsOfSubscribeCollection('transactions'))
    ->addResultField('id', 'block_id', 'balance_delta')
    ->addFilter('balance_delta', Filters::GT, '0x5f5e100');

// Get result with handle and start watching
$result = $net->subscribeCollection($query);

echo "Handle: {$result->getHandle()}." . PHP_EOL;

$counter = 0;

// Iterate generator
foreach ($result->getIterator() as $event) {
    $counter++;

    echo "Event counter: {$counter}, event data:" . PHP_EOL;
    var_dump($event->getResult());

    if ($counter > 25) {
        echo 'Manual stop watching.' . PHP_EOL;
        $result->stop(); // or call: $net->unsubscribe($result->getHandle());
    }
}

echo 'Finished.' . PHP_EOL;

详细示例

示例

有关详细使用方法的更多信息，请参阅示例和集成测试。

⚠️ 注意

我们使用实验性的PHP 扩展 FFI。此扩展允许在纯 PHP 中加载共享库、调用 C 函数和访问 C 数据结构。这是与 TON SDK 库异步集成的唯一方法。

请阅读 php 开发者的官方警告

警告：此扩展是实验性的。此扩展的行为（包括其函数名称以及与此扩展相关的任何其他文档）可能会在未来版本的 PHP 中发生更改，恕不另行通知。应自行承担使用此扩展的风险。

FFI 简介

尽管这样可以工作，但此功能并不支持所有 libffi 平台，效率不高，且在请求结束时泄漏资源。

PHP 回调

我们没有检测到内存泄漏。但在测试过程中，我们有时会遇到段错误。🙏 希望FFI扩展将在php的未来版本中得到稳定。

变更日志

有关最近更改的更多信息，请参阅变更日志。

测试

运行以下命令以运行单元测试

make test-unit

...以及集成测试

make test-integration

某些测试使用 TON SDK 方法来监听异步事件。这些事件的数据将保存到目录/tests/Integration/artifacts/中。这样，您可以详细分析它们。例如，测试\Extraton\Tests\Integration\TonClient\ProcessingTest::testProcessMessageWithEvents使用了方法\Extraton\TonClient\Processing::processMessage的调用。在生成器迭代期间接收到的事件将保存到文件中。

代码质量

我们使用PHPStan和PHP Coding Standards Fixer来控制代码质量。运行以下命令以分析代码并修复代码风格错误

make analyze

make codestyle

make codestyle-fix

贡献

有关详细信息，请参阅贡献指南。

注意

如果您有任何问题，请在此存储库中自由创建问题，谢谢！

鸣谢

许可证

Apache许可证版本2.0。有关更多信息，请参阅许可证文件。

saloeater / php-ton-client

维护者

详细信息