Download the PHP package iliaal/fastjson without Composer

fastjson

Fast JSON encode, decode, and validate for PHP 8.1+. Drop-in alternative to ext/json with a namespaced fastjson_* API and json_last_error-compatible error reporting. Backed by yyjson 0.12.0, one of the fastest portable JSON libraries. Coexists with ext/json; adoption is opt-in per call site.

Status: pre-release. yyjson 0.12.0 is vendored and linked. The fastjson_encode / fastjson_decode / fastjson_validate trio plus fastjson_last_error / _msg / _pos / _info, the file helpers fastjson_file_decode / fastjson_file_encode, and the JSON Pointer / patch helpers fastjson_pointer_get / _exists / _set (RFC 6901) and fastjson_merge_patch (RFC 7386) are available. The compat harness against php-src/ext/json/tests/*.phpt passes everything targeting features fastjson aims to mirror; the rest is categorized in tests/upstream-json/.skiplist.

📦 Install

On a minimal PHP image (e.g. php:8.x-cli from Docker Hub), PIE needs a few build tools installed first:

From source

Windows binaries

Pre-built 64-bit DLLs for PHP 8.1 through 8.5 (TS/NTS) are attached to each GitHub release.

🛠️ Usage

Function signatures track ext/json so call sites migrate by search-and-replace from json_* to fastjson_*. PHP 8.4 property hooks and JsonSerializable are honored.

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

Decode flags: JSON_OBJECT_AS_ARRAY, JSON_BIGINT_AS_STRING, JSON_INVALID_UTF8_IGNORE, JSON_INVALID_UTF8_SUBSTITUTE, JSON_THROW_ON_ERROR, and the fastjson-only FASTJSON_DECODE_RELAXED (tolerates the JSONC subset ext/json rejects: // and /* */ comments, trailing commas, and a leading UTF-8 BOM).

Validate flags: JSON_INVALID_UTF8_IGNORE (other bits raise ValueError per ext/json's contract). $depth is enforced on the success path like ext/json: documents nesting $depth or more containers deep validate false with a depth error.

Beyond the core trio: fastjson_file_decode() / fastjson_file_encode() read and write a JSON file in one call through the PHP streams layer (open_basedir and stream wrappers apply). fastjson_file_encode() opens the destination in write mode, so it is a convenience helper, not an atomic config/state-file update primitive; use your own temp-file + rename flow when partial writes would be unsafe. File I/O failures reuse FASTJSON_ERROR_SYNTAX to stay compatible with the JSON_ERROR_* code range, so callers that need to separate filesystem faults from parse or encode failures should check fastjson_last_error_msg() for the Failed to ... file messages. fastjson_pointer_get() extracts a single value by RFC 6901 JSON Pointer without materializing the rest of the document; fastjson_pointer_exists() reports whether a pointer resolves (distinguishing "present but null" from "absent"); fastjson_pointer_set() sets a single value by pointer and returns the re-serialized document, splicing the edit directly into the parsed document so a single edit on a large document skips a full decode/re-encode. Formatting and escaping flags apply to the whole pointer-set output; value-transforming flags apply only to the replacement. Pointer-set rejects an ambiguous target member duplicated in an object. fastjson_merge_patch() applies an RFC 7386 merge patch and canonicalizes duplicate members at each merged object using the last value and first insertion position. Merge-patch member matching always uses the raw JSON key bytes. JSON_INVALID_UTF8_IGNORE and JSON_INVALID_UTF8_SUBSTITUTE sanitize only the materialized PHP result, so malformed and valid key spellings that sanitize to the same PHP key remain distinct during the merge.

Error location: beyond fastjson_last_error() / _msg(), fastjson_last_error_pos() returns the byte offset of the most recent parse error (-1 when none), and fastjson_last_error_info() bundles ['code', 'msg', 'pos', 'line', 'col'] (1-based line/column) in one call, useful when a caller, or an agent, needs to point at exactly where malformed JSON broke. Under JSON_THROW_ON_ERROR the thrown class is JsonException when ext/json is present, Fastjson\JsonException otherwise.

See CHANGELOG.md for the full feature list and the divergences from ext/json that fastjson does not aim to mirror byte-for-byte.

📊 Performance

Throughput vs ext/json on the full 14.8 MB / 15-file canonical corpus from simdjson_php's jsonexamples. i9-13950HX, release build of both PHP and fastjson (-O2, Debug Build => no):

A visual side-by-side against ext/json on PHP 8.4 is published at iliaal.github.io/fastjson. Methodology, per-file numbers, small-corpus + per-call latency breakdown, and how to reproduce: bench/baseline.md.

Memory tradeoff

fastjson trades memory for speed on decode (yyjson's two-stage parser holds the doc alongside the zval tree). Decode peak is ~1.7x ext/json's heap. Encode runs one-stage (direct-write into smart_str using yyjson primitives) so encode memory is at near-parity with ext/json (~1.1x). Validate peaks at ~101x: lower than ext/json's true streaming validator (constant ~80 bytes) but already 2.7x better than yyjson's stock read path thanks to vendor patch P-002. See vendor/yyjson/PATCHES.md. For most callers the speedup is worth the memory headroom; if you're validate-heavy on giant inputs in tight memory_limit settings, it's a real consideration.

✨ What's in the box

• Bundled yyjson 0.12.0 (MIT) with five local patches (P-001 through P-005). Full notes and the mechanically replayable series are in vendor/yyjson/patches/.
• yyjson allocator routes every malloc/realloc/free through Zend's emalloc/erealloc/efree. JSON allocations participate in memory_limit accounting and request-scoped cleanup.
• FASTJSON_ERROR_* constants intentionally match all JSON_ERROR_* numeric values, so callers can use either set. yyjson groups raw control-character and invalid-surrogate parse failures under the UTF-8 code; the aliases exist even where fastjson does not currently emit the more specific ext/json category.
• 67-test compat harness rewritten from php-src/ext/json/tests/*.phpt runs alongside the native phpt suite. tests/upstream-json/.skiplist and tests/upstream-json/STATE.md track which upstream tests fastjson does not aim to pass byte-for-byte.
• Depth and stack-overflow guards use zend_call_stack_overflowed where Zend exposes it and conservative recursion caps elsewhere. Deeply chained inputs fail cleanly instead of being killed by the OS.

Roadmap

• [x] fastjson_validate success-path depth enforcement (allocation-free nesting scan; the validate-only fast path is kept)
• [ ] Streaming / incremental decode and encode

🔗 Native PHP extensions

Companion native PHP extensions:

• php_excel: native Excel I/O via LibXL. 7-10× faster than PhpSpreadsheet, full XLS/XLSX with formulas, formatting, and styling.
• mdparser: native CommonMark + GFM markdown parser via md4c. 15-30× faster than pure-PHP libraries.
• php_clickhouse: native ClickHouse client speaking the wire protocol directly. Picks up where SeasClick left off.
• pdo_duckdb: PDO driver for DuckDB, analytical SQL in your PHP stack.
• phpser: decoder-optimized binary serializer for cache workloads. Faster than igbinary on packed numerics and DTO batches.
• fast_uuid: high-throughput UUID generation (v1/v4/v7), batched CSPRNG and SIMD hex formatter, ramsey-compatible API.
• fastchart: native chart-rendering extension. 38 chart types behind one fluent OO API, SVG-canonical with PNG/JPG/WebP and optional PDF output.
• statgrab: system statistics (CPU, memory, disk, network) via libstatgrab, no parsing /proc by hand.
• phonetic: native phonetic name matching (Double Metaphone, Beider-Morse, Daitch-Mokotoff, NYSIIS, Match Rating), the encoders PHP core lacks.

License

• Wrapper code (fastjson*.c, php_fastjson.h) under BSD 3-Clause.
• Bundled yyjson sources under MIT. Upstream LICENSE preserved verbatim and surfaced in Section 2 of the project LICENSE file.

Follow @iliaa on X • Blog • If this sped up your stack, ⭐ star it!