Download the PHP package iliaal/phpser without Composer

phpser

A PHP serialization extension in C, targeting read-heavy cache workloads where decode time matters more than encode time or payload size.

Why phpser?

PHP cache workloads pay decode cost on every read. Encode happens once per write. The default igbinary was the right answer for over a decade, but lags on three shapes that show up everywhere: packed numeric arrays, deep-nested structures, and same-class DTO batches (Laravel queue payloads, cached models).

phpser is decoder-optimized. Pointer-equality dict intern, refcount-reuse of zend_strings, pre-sized hash tables with direct arPacked writes, tagged scalar runs. On the shapes above, it cuts size by 60-65% and decode time by 70-77% vs igbinary. On general-purpose rowsets it sits within 1% of igbinary's size with 25% faster encode and ~5% slower decode.

Not a universal win. Encode on small rowsets (100 rows) costs +30% over igbinary, and object-heavy mixed shapes pay +42% on encode because obj->handlers->get_properties is per-object. The bench table below has the full shape-by-shape breakdown.

Install

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

unzip is load-bearing on Debian: composer shells out to /usr/bin/unzip when extracting PIE's prebuilt-binary zip. If unzip is missing, composer silently falls back to PHP's ZipArchive which lays the .so out at a path PIE doesn't check, and install fails with ExtensionBinaryNotFound even though the zip downloaded fine.

From source

Pre-built binaries

Pre-built .dlls for Windows (PHP 8.3-8.5, TS/NTS, x64) and .sos for Linux glibc (x86_64, arm64) and macOS arm64 (PHP 8.4-8.5) are attached to each GitHub release. PIE fetches the matching binary automatically; falls back to source-build when no asset matches.

Usage

Basic round-trip. The encoded payload is opaque bytes; treat it as a binary blob in storage (no JSON-safety, no UTF-8 guarantees):

HMAC-signed mode for untrusted storage (memcached, redis, files, cookies). The signed entry points wrap the payload in a constant-time HMAC-SHA256 frame; tampered or foreign-keyed input is rejected before any decoding work runs:

allowed_classes option on both unserialize entry points. Same shape as PHP's native unserialize($payload, ['allowed_classes' => ...]):

When decoding attacker-controlled bytes, use one of the two restricted modes or the signed entry point. See SECURITY.md for the full threat model.

✨ Features

• Signed payloads for integrity. phpser_serialize_signed($value, $key) wraps the payload in an HMAC-SHA256 frame; phpser_unserialize_signed($payload, $key) verifies in constant time and rejects tampered or foreign-keyed input before any decoding work runs. Use this whenever the storage layer crosses a trust boundary: memcached, redis, files, cookies, anywhere an attacker who can write to the store could otherwise feed a crafted payload to your decoder.
• Safe handling of untrusted input. allowed_classes option on both unserialize entry points, matching PHP's native unserialize($payload, ['allowed_classes' => ...]) shape: pass false to reject all classes, an array to allowlist specific ones, or true for the default. Disallowed classes decode as __PHP_Incomplete_Class with the original name preserved, never instantiated. Recursion depth is capped at 512 on both encode and decode (encode throws, decode returns null), and assoc decode uses zend_hash_update so duplicate-key payloads collapse to last-write-wins rather than phantom buckets.
• PHP 8.3+ (8.4, 8.5, master). BSD 3-Clause.

Bench (opt PHP 8.4.22-dev NTS release, 1000 iters, median of 9 runs)

Wins: packed numerics ~65% smaller + ~75% faster decode + ~61% faster encode. Deep-nested ~49% faster encode at parity size. Rowset_1000 encode beats igbinary by ~25%, size within 1.1%; decode pays a ~5% tax for the front-loaded dict header walk + refcount-reuse machinery. DTO workloads (Laravel-queue-style payloads, single-class arrays): 10-12% smaller, 11-14% faster decode vs igbinary thanks to dict dedup on prop names + the class-entry lookup cache that amortizes zend_lookup_class_ex across same-typed batches.

rowset_100 encode (+30%) is the durable gap: a fixed-cost floor for the dict header emission and first-row inline emissions, amortized over too few rows to recover. The absolute time is small (11 µs for the entire 100-row payload). Decode is essentially at parity (per-run delta median +0.4%, absolute ratio +6%): the skip-DICT cache-eviction policy keeps ['a','b','c']-style repeated values in DICT slots so detect_packed_run picks the TAG_PACKED_STRINGS typed-run path instead of falling back to PACKED_MIXED mid-rowset.

dto_mixed encode (+42%) is the durable encode gap on object-heavy shapes: obj->handlers->get_properties is called per object and isn't trivially avoidable without a custom fast path for default property layouts.

Design highlights

The core ideas that drive the perf wins above:

• Pointer-equality dict intern. Encoding hits a *zend_string == *zend_string check first; only on miss do we hash the bytes. Cuts intern cost to near-zero for rowset-shaped data where PHP literals share interned zend_strings.
• Front-loaded string dictionary. Same shape as igbinary's compact_strings, except we emit the table once at the head and reference by varint index from values. Trade-off: not streamable.
• Refcount-reuse of zend_strings on decode. Per-decode cache parallel to the dict. First reference allocates, subsequent ones addref.
• HT_IS_PACKED detection via flag, not iteration. Avoid scanning the buckets just to determine layout.
• arPacked stride awareness. PHP 8+'s packed-array layout stores zvals directly, not Buckets. Stride is 16, not 32.
• Sparse-packed fallback. Arrays with holes (post-unset) preserve original int keys via Assoc rather than silently re-indexing.

Where phpser diverges from igbinary

igbinary is the closest reference point. The areas where there's still measurable perf to take, and that this project targets, are:

1. Pre-sized HT + direct arPacked writes on decode. When the wire format declares PACKED_LEN N, allocate the HT once via zend_new_array(N) and write directly into arPacked with ZVAL_* macros. Skips N zend_hash_next_index_insert calls, including their hash computation, growth checks, and capacity tuning. Shipped.
2. Tagged scalar runs. [1, 2, 3, ...] (1000 longs) emits as a single PACKED_LONGS header + N zigzag varints, not 1000 (tag, varint) pairs. Decode is one tight loop with no per-element tag dispatch. Shipped.
3. Inline-cache pointer intern. 16-slot ring of recently-seen zend_string*. Hit rate near 100% on rowset shapes (PHP interns literals; the same "id" zend_string pointer flows through every row). Skips the byte-hash entirely on cache hits. Shipped.
4. Eager dict materialization with warm hashes. All dict zend_strings allocated up front during header parse and their hashes pre-computed. zend_hash_add_new reuses the cached hash. Shipped.
5. update insert on assoc decode. Originally add_new to skip the existence-check, but adversarial wire payloads with duplicate keys would produce phantom buckets that violate PHP's last-write-wins semantic (count($arr) != count(array_unique(array_keys($arr)))). Reverted to zend_hash_update for security-boundary correctness; add_new is a real but small perf win the cost of breaking adversarial payloads cleanly. Shipped.

6. Inline-short-string tag with upgrade-on-second-encounter. TAG_STR_INLINE (0x0c) and KEY_STR_INLINE (0x02) are emitted on a string's first occurrence; the next occurrence triggers an in-place upgrade to a dict entry, and all subsequent ones emit TAG_STR_DICT. Singletons (e.g. row_X values in a rowset) never hit the upgrade branch. They cost nothing in the dict header. The intern cache doubles as the "seen once?" signal: high bit of idx distinguishes INLINE_EMITTED from DICT_IDX. No pre-pass; single walk of the zval tree as before.

   A count-then-emit variant was tried first: pre-walk the zval tree to tag occurrences, then emit inline for singletons and dict for repeats. The pre-pass cost ~200 ns per string and ate the per-singleton savings, so the single-walk upgrade-on-second-encounter version above is what ships. rowset_1000 encode landed at 25% faster than igbinary (up from 8% in the pre-upgrade implementation), with payload size dropping from +5% to +2.7%.

7. Skip refcount machinery during build. All zvals built during decode are fresh and unshared until handed back to PHP. Internal writes can skip Z_TRY_ADDREF guards.

Local dev build

The hand-rolled Makefile builds against an in-tree ~/php-src-8.4-opt checkout without phpize/autoconf. Useful for hacking on the extension while also hacking on PHP itself:

Override PHP_SRC= to target a different in-tree PHP checkout. Load alongside igbinary for the A/B bench:

The config.m4 auto-detects the session extension and registers phpser as a session.serialize_handler when available.

Limitations / known gaps

• Recursion depth is capped at 512 on both encode and decode. On decode, anything deeper than 512 nested containers / refs is rejected (returns null) to bound stack consumption against adversarial wire payloads. On encode, input deeper than 512 throws an Exception rather than silently shipping a truncated payload. Object cycles are preserved correctly via the id-table machinery and don't count against this cap for shared-graph cases; the cap only fires on genuinely deep trees. Cache workloads typically nest 5-10 deep, so the cap is many orders of magnitude past any legitimate payload.
• Closures and resources encode as NULL. Same shape as PHP's own serialize(); these types are inherently non-serializable.
• Unknown classes at decode fall back to stdClass rather than PHP's __PHP_Incomplete_Class. This is deliberate for the typical cache workload; allowed_classes => [...] produces __PHP_Incomplete_Class with the original name preserved for disallowed classes, matching PHP.
• session.serialize_handler=phpser is shipped (compiled in when phpize detects the session extension; gated on HAVE_PHP_SESSION so the extension still loads on session-less PHP builds). phpredis integration is not yet wired; call phpser_serialize/unserialize directly when using the extension as a phpredis serializer.

Wire format (V1)

Varints are LEB128 (unsigned); signed values use zigzag encoding. Tags 0x10/0x11 plus 0x0a/0x0d/0x0e/0x0f each implicitly claim the next id in encounter order, so the decoder reconstructs back-refs by counting container tags as it parses.

🔗 PHP Performance Toolkit

Companion native PHP extensions:

• php_excel: native XLS/XLSX read/write via LibXL
• mdparser: native CommonMark + GitHub Flavored Markdown parser
• php_clickhouse: native ClickHouse client over the binary protocol
• fastchart: 19 chart types in one PHP extension
• fastjson: drop-in faster ext/json, backed by yyjson
• statgrab: system statistics wrapper around libstatgrab

Follow on X • Blog • If this cut your cache decode CPU, ⭐ star it!