README

一个用于与TRON协议交互的PHP API

基于 iexbase/tron-api

安装

composer require dsdcr/tron

要求

支持的PHP版本：

• PHP 7.4+

配置

本包支持新的、更直观的配置结构：

新配置结构

'network' => 'mainnet',        // 网络名称: mainnet, testnet, nile
'use_solidity' => false,       // 布尔值: true表示使用Solidity节点，false表示使用Full节点
'networks' => [
    'mainnet' => [
        'host' => 'https://api.trongrid.io',
        'explorer' => 'https://tronscan.org'
    ],
    'testnet' => [
        'host' => 'https://api.shasta.trongrid.io',
        'explorer' => 'https://shasta.tronscan.org'
    ],
    'nile' => [
        'host' => 'https://nile.trongrid.io',
        'explorer' => 'https://nile.tronscan.org'
    ]
]

使用

Laravel 使用方式

1. 在Laravel中安装

composer require dsdcr/tron

2. 发布配置

php artisan vendor:publish --provider="Dsdcr\Tron\TronServiceProvider"

3. 环境配置

在.env文件中添加：

TRON_NETWORK=mainnet
TRON_USE_SOLIDITY=false
TRON_API_KEY=您的TronGrid API密钥
TRON_PRIVATE_KEY=您的私钥
TRON_ADDRESS=您的地址
TRON_TIMEOUT=30000

4. Laravel使用示例

使用依赖注入：

<?php

namespace App\Http\Controllers;

use Dsdcr\Tron\Tron;

class TronController extends Controller
{
    protected $tron;

    public function __construct(Tron $tron)
    {
        $this->tron = $tron;
    }

    public function getBalance($address)
    {
        return $this->tron->getBalance($address, true);
    }

    public function sendTrx($to, $amount)
    {
        return $this->tron->send($to, $amount);
    }
}

使用门面：

<?php

use Dsdcr\Tron\Facades\Tron;

// 获取账户信息
$account = Tron::getAccount('TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t');

// 获取余额
$balance = Tron::getBalance('TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t', true);

// 发送TRX
$result = Tron::send('接收地址', 1.5);

// 获取最新区块
$blocks = Tron::getLatestBlocks(10);

服务类示例：

<?php

namespace App\Services;

use Dsdcr\Tron\Tron;

class TronService
{
    protected $tron;

    public function __construct(Tron $tron)
    {
        $this->tron = $tron;
    }

    public function getUserBalance($address)
    {
        try {
            return $this->tron->getBalance($address, true);
        } catch (\Exception $e) {
            \Log::error('TRON余额查询错误: ' . $e->getMessage());
            return 0;
        }
    }

    public function transferTrx($fromPrivateKey, $toAddress, $amount)
    {
        try {
            $this->tron->setPrivateKey($fromPrivateKey);
            return $this->tron->send($toAddress, $amount);
        } catch (\Exception $e) {
            \Log::error('TRON转账错误: ' . $e->getMessage());
            return false;
        }
    }
}

普通PHP使用方式

1. 使用TronConfig助手(推荐)

<?php

require_once 'vendor/autoload.php';

use Dsdcr\Tron\TronConfig;

// 方法1: 使用默认配置
$tron = TronConfig::create(); // 主网 + 全节点

// 方法2: 指定网络和节点类型
$tron = TronConfig::create('mainnet', true); // 主网 + 合约节点
$tron = TronConfig::create('testnet', false); // 测试网 + 全节点

// 方法3: 使用自定义头部
$tron = TronConfig::create('mainnet', false, [
    'TRON-PRO-API-KEY' => '您的API密钥'
], 30000);

// 方法4: 使用完整配置
$config = [
    'network' => 'mainnet',
    'use_solidity' => false,
    'timeout' => 30000,
    'headers' => [
        'TRON-PRO-API-KEY' => '您的API密钥'
    ],
    'networks' => [
        'mainnet' => [
            'host' => 'https://api.trongrid.io',
            'explorer' => 'https://tronscan.org'
        ]
    ]
];

$tron = TronConfig::createFromConfig($config);

2. 传统HttpProvider使用方式

<?php

require_once 'vendor/autoload.php';

use Dsdcr\Tron\Tron;
use Dsdcr\Tron\Provider\HttpProvider;

// 创建提供者
$fullNode = new HttpProvider('https://api.trongrid.io');
$solidityNode = new HttpProvider('https://api.trongrid.io');
$eventServer = new HttpProvider('https://api.trongrid.io');

// 创建Tron实例
try {
    $tron = new Tron($fullNode, $solidityNode, $eventServer);
} catch (\Dsdcr\Tron\Exception\TronException $e) {
    exit($e->getMessage());
}

3. 完整PHP示例

<?php

require_once 'vendor/autoload.php';

use Dsdcr\Tron\TronConfig;

try {
    // 初始化主网Tron实例
    $tron = TronConfig::create('mainnet', false, [
        'TRON-PRO-API-KEY' => '您的API密钥'
    ]);

    // 设置交易私钥
    $tron->setPrivateKey('您的私钥');
    $tron->setAddress('您的地址');

    // 获取账户余额
    $balance = $tron->getBalance('TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t', true);
    echo "余额: " . $balance . " TRX\n";

    // 获取账户信息
    $account = $tron->getAccount('TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t');
    echo "账户类型: " . $account['type'] . "\n";

    // 发送TRX (需要私钥)
    // $result = $tron->send('接收地址', 1.5);

    // 生成新地址
    $newAccount = $tron->createAccount();
    echo "新地址: " . $newAccount['address'] . "\n";
    echo "私钥: " . $newAccount['privateKey'] . "\n";

    // 获取最新区块
    $blocks = $tron->getLatestBlocks(5);
    echo "最新区块号: " . $blocks[0]['block_header']['raw_data']['number'] . "\n";

    // 与智能合约交互
    $contract = $tron->contract('TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t'); // USDT合约

} catch (\Exception $e) {
    echo "错误: " . $e->getMessage() . "\n";
}

网络配置

可用网络

• mainnet: TRON主网(生产环境)
• testnet: Shasta测试网(开发环境)
• nile: Nile测试网(开发环境)

节点类型

• 全节点 (use_solidity = false): 用于发送交易，获取最新数据
• 合约节点 (use_solidity = true): 用于查询智能合约，历史数据

动态网络切换

// 不同网络实例
$mainnetTron = TronConfig::create('mainnet');
$testnetTron = TronConfig::create('testnet');
$nileTron = TronConfig::create('nile');

// 不同节点类型
$fullNodeTron = TronConfig::create('mainnet', false);
$solidityNodeTron = TronConfig::create('mainnet', true);

基础示例

快速开始示例

<?php

require_once 'vendor/autoload.php';

use Dsdcr\Tron\TronConfig;

// 使用新配置快速设置
$tron = TronConfig::create('mainnet', false, [
    'TRON-PRO-API-KEY' => '您的API密钥'
]);

// 生成新地址
$generateAddress = $tron->createAccount();
echo $generateAddress['address']; // TKttnV3FSY1iEoAwB4N52WK2DxdV94KpDd
echo $generateAddress['privateKey']; // 7d507c48da396a6b0dbe09f21f729dd2ba29d9a5e5bf8edde5fc9144c7ebe261
echo $generateAddress['publicKey']; // 0337e1a88b108c438266c3ca5c5a73a8b6803443c4f7e1b1d140b11106a4e7d88f

// 获取账户余额
$balance = $tron->getBalance('TKttnV3FSY1iEoAwB4N52WK2DxdV94KpDd', true);

// 发送TRX
$tron->setPrivateKey('7d507c48da396a6b0dbe09f21f729dd2ba29d9a5e5bf8edde5fc9144c7ebe261');
$tron->setAddress('TKttnV3FSY1iEoAwB4N52WK2DxdV94KpDd');

$transfer = $tron->send('TLsV52sRDL79HXGGm9yzwKibb6BeruhUzy', 0.1);

传统HttpProvider示例

<?php

require_once 'vendor/autoload.php';

use Dsdcr\Tron\Tron;
use Dsdcr\Tron\Provider\HttpProvider;

$fullNode = new HttpProvider('https://api.trongrid.io');
$solidityNode = new HttpProvider('https://api.trongrid.io');
$eventServer = new HttpProvider('https://api.trongrid.io');

try {
    $tron = new Tron($fullNode, $solidityNode, $eventServer);
} catch (\Dsdcr\Tron\Exception\TronException $e) {
    exit($e->getMessage());
}

// 使用方式同上...

高级功能

智能合约交互

// 获取合约实例
$contract = $tron->contract('TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t'); // USDT合约

// 调用合约方法
$result = $contract->call('balanceOf', 'T地址...');

// 发送合约交易
$tron->setPrivateKey('您的私钥');
$result = $contract->send('transfer', '接收地址...', 1000000); // 1 USDT

交易管理

// 创建交易
$transaction = $tron->getTransactionBuilder()->sendTrx('接收地址...', 1000000, '发送地址...');

// 签名交易
$signedTransaction = $tron->signTransaction($transaction);

// 广播交易
$result = $tron->sendRawTransaction($signedTransaction);

区块和交易查询

// 获取最新区块
$blocks = $tron->getLatestBlocks(10);

// 按区块号获取区块
$block = $tron->getBlock(12345);

// 按ID获取交易
$transaction = $tron->getTransaction('交易ID');

// 获取账户交易记录
$transactions = $tron->getTransactionsFromAddress('T地址...', 50);

配置迁移

从旧配置迁移

// 旧方式(仍支持)
'host' => 'https://api.trongrid.io',
'node_type' => 'fullnode',

迁移到新配置

// 新方式(推荐)
'network' => 'mainnet',
'use_solidity' => false,

错误处理

use Dsdcr\Tron\Exception\TronException;

try {
    $tron = TronConfig::create('mainnet');
    $balance = $tron->getBalance('无效地址');
} catch (TronException $e) {
    echo "TRON API错误: " . $e->getMessage();
} catch (\Exception $e) {
    echo "一般错误: " . $e->getMessage();
}

最佳实践

1. 使用环境变量: 将私钥等敏感数据存储在环境变量中
2. 错误处理: 始终在try-catch块中包装API调用
3. 网络选择: 开发使用测试网，生产使用主网
4. API密钥: 使用TronGrid API密钥以获得更好的速率限制
5. 节点类型: 交易使用全节点，查询使用合约节点

API文档

详细API文档请参考：

• NEW_CONFIG_GUIDE.md - 新配置结构指南
• TRON开发者文档
• TronGrid API文档

测试

composer test

示例

查看examples/目录获取更多使用示例：

• new-config-simple.php - 基础新配置使用
• config-based-example.php - 高级配置示例
• final-verification.php - 综合功能测试

更新日志

v2.0.0

• ✅ 新的配置结构，使用network和use_solidity
• ✅ TronConfig助手类简化设置
• ✅ 支持多网络(mainnet, testnet, nile)
• ✅ 向后兼容旧配置
• ✅ 改进Laravel集成

贡献

欢迎贡献！请随时提交Pull Request。

许可证

MIT许可证。详情请见许可证文件。