web3p/web3.php无法解码Solidity合约返回的tuple[]（结构体数组）问题求助

问题背景 #

我在本地Hardhat节点上部署了一个NFT市场合约，其中包含一个返回结构体数组的视图函数，具体定义如下：

Solidity合约代码片段 #

struct MarketItem {
    uint256 tokenId;
    address payable seller;
    address payable owner;
    uint256 price;
    bool sold;
}

function fetchMarketItems() public view returns (MarketItem[] memory) {
    // 函数实现逻辑
}

对应ABI片段 #

{
  "inputs": [],
  "name": "fetchMarketItems",
  "outputs": [
    {
      "components": [
        {
          "internalType": "uint256",
          "name": "tokenId",
          "type": "uint256"
        },
        {
          "internalType": "address payable",
          "name": "seller",
          "type": "address"
        },
        {
          "internalType": "address payable",
          "name": "owner",
          "type": "address"
        },
        {
          "internalType": "uint256",
          "name": "price",
          "type": "uint256"
        },
        {
          "internalType": "bool",
          "name": "sold",
          "type": "bool"
        }
      ],
      "internalType": "struct NFTMarketplace.MarketItem[]",
      "name": "",
      "type": "tuple[]"
    }
  ],
  "stateMutability": "view",
  "type": "function"
}

已正常工作的实现（JS/ethers.js） #

使用ethers.js调用该函数可以完美解码并返回结构体数组：

if (!NFTMarketplaceABI) await loadABI();
const provider = new ethers.providers.JsonRpcProvider(); // 连接Hardhat本地节点
const contract = new ethers.Contract(
  "0x5FbDB2315678afecb367f032d93F642f64180aa3",
  NFTMarketplaceABI,
  provider
);
const data = await contract.fetchMarketItems();
console.log(data); // 正常返回：结构化的市场项数组

PHP/web3p/web3.php中遇到的问题 #

环境信息 #

• PHP 8.x + Laravel框架
• 使用web3p/web3.php库的Contract/HttpProvider/HttpRequestManager组件
• Hardhat节点在Docker环境中，可通过http://172.17.0.1:8545访问

调用代码实现 #

$provider = new HttpProvider(new HttpRequestManager('http://172.17.0.1:8545'));
$contractAddress = '0x5FbDB2315678afecb367f032d93F642f64180aa3';
$abiPath = app()->basePath('public/NFTMarketplace.json');
$abiJson = json_decode(file_get_contents($abiPath), true);

if (!isset($abiJson['abi'])) {
    throw new \Exception('ABI文件未找到');
}

$contract = new Contract($provider, $abiJson['abi']);
$contract->at($contractAddress);

// 健康检查：确认目标地址是有效合约
$contract->eth->getCode($contractAddress, 'latest', function ($e, $code) {
    if ($e !== null) throw new \Exception($e->getMessage());
    if ($code === '0x' || $code === '0x0') throw new \Exception('目标地址不是合约地址');
});

$items = [];
$errMsg = null;

$contract->call('fetchMarketItems', [], function ($err, $result) use (&$items, &$errMsg) {
    if ($err !== null) {
        $errMsg = $err->getMessage();
        return;
    }
    $items = $result ?? [];
});

if ($errMsg) {
    throw new \RuntimeException("调用fetchMarketItems失败: {$errMsg}");
}

实际错误表现 #

回调函数始终收到解码错误，典型错误信息如下：

fetchMarketItems failed: unsupported or invalid solidity type "tuple[]"

调试过程中还遇到过其他和ABI解码相关的报错。

已尝试的排查步骤 #

1. 验证合约地址有效性：通过eth_getCode确认返回非零字节码，地址正确
2. 一致性校验：使用和ethers.js完全相同的ABI文件
3. 网络连通性测试：尝试了127.0.0.1:8545和Docker宿主地址172.17.0.1:8545，均能正常连接节点
4. 功能兼容性测试：调用返回单一uint256的简单函数，可正常解码返回值
5. 文档/社区搜索：查阅web3p/web3.php的官方文档和GitHub Issues，未找到明确的tuple[]支持说明

我的疑问 #

1. web3p/web3.php是否支持解码Solidity合约返回的动态结构体数组（即tuple[]类型）？
2. 如果支持，正确的调用方式或ABI定义应该是什么样的？如何让Contract->call('fetchMarketItems')返回解码后的结构化数据？
3. 如果该库不支持，PHP生态中有哪些可行的替代方案？比如修改合约返回并行数组、使用其他ABI解码包、或者更换其他PHP Web3库？

内容来源于stack exchange