FastJSON：PHP 最快的 JSON 库，比 ext/json 快 6 倍！

概述

适用于 PHP 8.3+ 的高速 JSON 编码、解码和验证库。

它是 ext/json 的可直接替代品（drop-in alternative），提供带命名空间的 fastjson_* API，并兼容 json_last_error 错误报告机制。底层基于 yyjson 0.12.0 —— 业界最快的跨平台 JSON 库之一。可与 ext/json 共存，采用方式为按调用点自主选择。

📦 安装

# PIE（PHP Foundation 官方扩展安装器，使用仓库根目录的 composer.json，类型为 "php-ext"）
pie install iliaal/fastjson

在极简 PHP 镜像中（如 Docker Hub 的 php:8.x-cli），需先安装构建工具：

Debian/Ubuntu

sudo apt install -y git bison libtool-bin

macOS

brew install bison libtool

从源码编译

git clone https://github.com/iliaal/fastjson.git
cd fastjson
phpize && ./configure --enable-fastjson
make -j
sudo make install
echo 'extension=fastjson.so' | sudo tee /etc/php/conf.d/fastjson.ini

Windows 二进制文件

每个 GitHub Release 都附带了 PHP 8.3、8.4、8.5 的预编译 DLL（TS/NTS，x86/x64）。

🛠️ 使用示例

$json = fastjson_encode(['hello' => 'world']);     // string|false
$data = fastjson_decode($json, assoc: true);       // mixed
$ok   = fastjson_validate($json);                  // bool

if ($data === null && fastjson_last_error() !== 0) {
    fwrite(STDERR, fastjson_last_error_msg());
}

函数签名尽量与 ext/json 保持一致，因此迁移时只需全局搜索替换 json_* 为 fastjson_* 即可。支持 PHP 8.4 的 property hooks 和 JsonSerializable 接口。

编码支持的标志（flags）： JSON_PRETTY_PRINT、JSON_UNESCAPED_SLASHES、JSON_UNESCAPED_UNICODE、JSON_FORCE_OBJECT、JSON_HEX_TAG、JSON_HEX_AMP、JSON_HEX_APOS、JSON_HEX_QUOT、JSON_NUMERIC_CHECK、JSON_PRESERVE_ZERO_FRACTION、JSON_PARTIAL_OUTPUT_ON_ERROR、JSON_INVALID_UTF8_IGNORE、JSON_INVALID_UTF8_SUBSTITUTE、JSON_THROW_ON_ERROR。

解码支持的标志： JSON_OBJECT_AS_ARRAY、JSON_BIGINT_AS_STRING、JSON_INVALID_UTF8_IGNORE、JSON_INVALID_UTF8_SUBSTITUTE、JSON_THROW_ON_ERROR。

验证支持的标志： 仅 JSON_INVALID_UTF8_IGNORE（其他位会按 ext/json 的约定抛出 ValueError）。

完整功能列表及与 ext/json 的差异请参阅 CHANGELOG.md。

📊 性能表现

在 simdjson_php 的 jsonexamples 完整 14.8 MB / 15 个文件的标准语料上进行的吞吐量对比（i9-13950HX，PHP 和 fastjson 均为 release 构建，-O2）：

包含 ext/json + PHP SIMD 优化及 simdjson_php 的完整可视化对比图见：iliaal.github.io/fastjson。详细方法、单文件数据、小语料延迟分析及复现方式请见 bench/README.md。

内存权衡

fastjson 在解码时用速度换内存（yyjson 的两阶段解析器会同时持有文档和 zval 树），峰值内存约为 ext/json 的 1.7x。 编码采用单阶段（通过 yyjson 原语直接写入 smart_str），内存占用与 ext/json 接近（约 1.1x）。 验证峰值内存约为 ext/json 的 101 倍（高于其真正的流式验证器），但通过供应商补丁 P-002 已比 yyjson 原版好 2.7 倍。 对大多数调用者来说，性能提升值得额外的内存开销；若你在极低 memory_limit 下大量验证超大输入，则需谨慎评估。

✨ 包含的功能

• 内置 yyjson 0.12.0（MIT 协议），包含三个本地补丁（已提交上游 ibireme/yyjson #263~#266），详见 vendor/yyjson/PATCHES.md。
• yyjson 分配器将所有 malloc/realloc/free 路由到 Zend 的 emalloc/erealloc/efree，JSON 分配参与 memory_limit 统计和请求域清理。
• FASTJSON_ERROR_* 常量故意与 JSON_ERROR_* 字节完全一致，可混用。
• 重写了 62 个兼容测试套件，与原生 phpt 测试一同运行。
• 编码和解码均通过 zend_call_stack_overflowed 实现深度和栈溢出防护，深层嵌套输入会优雅失败而非被 OS 杀死。

🔗 PHP 性能工具包

作者的其他高性能 PHP 原生扩展：

• php_excel：原生 Excel I/O，比 PhpSpreadsheet 快 7-10 倍，支持完整 XLS/XLSX（公式、格式、样式），基于 LibXL。
• mdparser：原生 CommonMark + GFM 解析器，比纯 PHP 实现快 15-30 倍，652/652 个规范示例全部通过。
• php_clickhouse：原生 ClickHouse 客户端，直接使用 wire 协议，接棒 SeasClick。
• fastchart：原生图表渲染扩展，19 种图表类型，流畅的面向对象 API，可与调用者拥有的 \GdImage 画布组合使用。