FastJSON: A Drop‑In PHP 8.3+ JSON Extension Up to 6× Faster Than ext/json

Overview

FastJSON is a high‑performance JSON encoding, decoding and validation library for PHP 8.3+. It is a drop‑in replacement for ext/json, providing namespaced fastjson_* functions and compatibility with json_last_error. The implementation is built on yyjson 0.12.0, one of the fastest cross‑platform JSON libraries.

Installation

Install via the PHP Foundation extension installer (PIE):

# PIE (PHP Foundation official extension installer
pie install iliaal/fastjson

On minimal PHP images (e.g., php:8.x-cli) you must first install build tools:

Debian/Ubuntu sudo apt install -y git bison libtool-bin macOS

brew install bison libtool

Build from source

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 binaries

Each GitHub release provides pre‑compiled DLLs for PHP 8.3, 8.4 and 8.5 (TS/NTS, x86/x64).

Usage example

$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());
}

The function signatures intentionally mirror ext/json, so a global search‑replace of json_* with fastjson_* is sufficient for migration. FastJSON also supports PHP 8.4 property hooks and the JsonSerializable interface.

Supported flags

Encoding 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.

Decoding flags : JSON_OBJECT_AS_ARRAY, JSON_BIGINT_AS_STRING, JSON_INVALID_UTF8_IGNORE, JSON_INVALID_UTF8_SUBSTITUTE, JSON_THROW_ON_ERROR.

Validation flags : only JSON_INVALID_UTF8_IGNORE (other bits follow ext/json’s convention and throw ValueError).

Performance

Decode (stdClass): fastjson 602 MB/s vs ext/json 227 MB/s → 2.66× faster.

Decode (assoc array): fastjson 628 MB/s vs ext/json 237 MB/s → 2.65× faster.

Encode: fastjson 1,092 MB/s vs ext/json 180 MB/s → 6.06× faster.

Validate: fastjson 1,352 MB/s vs ext/json 265 MB/s → 5.10× faster.

The benchmark uses the full 14.8 MB / 15‑file corpus from simdjson_php’s jsonexamples, with both PHP and fastjson built in release mode and compiled with -O2. Visual comparisons are available at iliaal.github.io/fastjson; detailed methodology and additional data are in bench/README.md.

Memory trade‑offs

During decoding, fastjson trades speed for memory: its two‑stage parser holds both the document and the zval tree, resulting in peak memory usage about 1.7× that of ext/json. Encoding uses a single‑stage approach (direct write to smart_str) and consumes roughly 1.1× the memory of ext/json. Validation can peak at 101× the memory of ext/json, though a vendor patch (P‑002) reduces this by 2.7×. For most workloads the performance gains outweigh the extra memory, but users with very low memory_limit should evaluate carefully when validating large inputs.

Included features

Bundled yyjson 0.12.0 (MIT) with three local patches (see vendor/yyjson/PATCHES.md).

yyjson allocator routes all malloc/realloc/free through Zend’s emalloc/erealloc/efree, integrating with memory_limit accounting.

FASTJSON_ERROR_* constants match JSON_ERROR_* byte‑for‑byte, allowing mixed use.

62 compatibility test cases rewritten and run alongside native phpt tests.

Depth and stack‑overflow protection via zend_call_stack_overflowed, causing graceful failure on deeply nested inputs.

Related high‑performance PHP extensions

php_excel : native Excel I/O, 7–10× faster than PhpSpreadsheet, based on LibXL.

mdparser : native CommonMark + GFM parser, 15–30× faster than pure PHP, passes all 652 specification examples.

php_clickhouse : native ClickHouse client using the wire protocol.

fastchart : native chart rendering extension with 19 chart types, object‑oriented API, compatible with \GdImage canvases.