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 leaves performance on the table for common cache shapes: database rowsets, packed numeric arrays, deep-nested structures, and same-class DTO batches (Laravel queue payloads, cached models).

phpser is decoder-optimized. It uses pointer-equality dict interning with a bounded content fallback, reuses decoded zend_strings by refcount, pre-sizes hash tables, writes straight into packed zval storage, and emits tagged scalar runs. On the current ARM benchmark, phpser beats igbinary on encode and decode in all ten cases. Integer ranges collapse to constant-size affine runs and decode 91-92% faster, shuffled integer arrays decode 73% faster, deep nesting decodes 22% faster, and DTO batches decode 53-63% faster.

Rowsets keep the pointer-equality fast path for shared strings, while columnar encoding also deduplicates low-cardinality strings and equal packed-string vectors by content. In rowset_distinct_1000, where equal repeated strings have separate allocations, phpser is 56% smaller, 63% faster to encode, and 51% faster to decode than igbinary.

📖 The design writeup: phpser: a fast, secure binary serializer for PHP cache workloads, on what the decoder does differently and why decode time is the metric to optimize. The interactive benchmark page compares phpser against igbinary, native serialize(), and msgpack across every cache shape.

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.2-8.5, TS/NTS, x86 and 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. An empty key is rejected on both sides. A keyless HMAC is forgeable, so callers must supply real key material.
• 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 bounded update semantics so duplicate-key payloads collapse to last-write-wins rather than phantom buckets. Wire-controlled keys run against a bounded collision budget, so a payload built around Zend's stable string hash cannot turn an array, property table, or rowset schema into quadratic decode work; a chain that exhausts the budget rejects the payload rather than grinding through it.
• PHP 8.2+ (8.3, 8.4, 8.5, master). BSD 3-Clause.

Bench (PHP 8.4.23 aarch64, idle box, 1000 iters, median of 35)

phpser encodes 12-84% faster and decodes 22-92% faster than igbinary across all ten cases. Integer ranges collapse to a 7-byte affine run and decode 91-92% faster; shuffled integers (packed_rand_10k) are 62% smaller, 29% faster to encode, and 73% faster to decode. Deep nesting is 32% faster to encode and 22% faster to decode with a five-byte size difference.

The table's rowset_100 and rowset_1000 reuse PHP literal strings, so the pointer-equality intern path remains the cheapest case. Columnar TAG_TABLE also performs a bounded content-cardinality scan for separately allocated strings and equal packed-string vectors. That makes rowset_distinct_1000 the same 25,993-byte payload as rowset_1000; against igbinary it is 56% smaller, 63% faster to encode, and 51% faster to decode.

DTO workloads (Laravel-queue-style payloads, single-class arrays) are now 22-34% smaller, 53-63% faster to decode, 12-21% faster to encode than igbinary. Wire-v2 TAG_OBJECT_SLOTS drops the per-property key indices and installs declared values straight into property slots; the dict dedups prop names once, and the class-entry lookup cache amortizes zend_lookup_class_ex across same-typed batches.

Sizes are byte-identical on x86 (the wire format is architecture-neutral); the ns/op columns are from an idle aarch64 box, median of 35. For the full four-way picture, phpser vs igbinary vs native serialize() vs msgpack, with size, encode, and decode side by side on every shape, see the interactive benchmark page. Regenerate it with php ... bench.php --html > docs/index.html.

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. Columnar rowsets additionally scan for at most eight distinct string values and prebind equal packed-string vectors, preserving dictionary reuse when database drivers return separate allocations for equal content.
• 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.
• Integer-run compression. Constant-stride runs (ranges, constant fills) collapse to a base+step affine tag a few bytes long, bounded by a one-million-element budget the encoder and decoder enforce identically. Other integer runs and rowset id columns store zigzag deltas whenever those encode smaller; wrapping mod-2^64 arithmetic keeps every int64 sequence exact with no overflow checks.
• 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. O(1) pointer-hash intern. Open-addressed zend_string* → slot hash, grown without eviction. Hit rate near 100% on literal rowset shapes (PHP interns literals; the same "id" zend_string pointer flows through every row), and unique value strings (names, emails) hit a single-probe miss instead of a linear scan. Separately allocated low-cardinality table columns use a bounded content scan, which puts encode ahead of igbinary on every measured shape. Skips the byte-hash entirely on pointer hits. Shipped.
4. Eager dict materialization with warm hashes. All dict slots are resolved up front during header parse, against the engine's interned-string table first. Property names, class names, and hot literals come back as the engine's own interned strings (no allocation, no refcount traffic, pointer-equality hash lookups), with a regular allocation as the fallback. Hashes are set on both paths; zend_hash_add_new reuses the cached hash. Shipped.
5. Invariant-gated add_new on assoc decode. Wire-controlled duplicate keys must collapse to last-write-wins rather than produce phantom buckets (count($arr) != count(array_unique(array_keys($arr)))), and canonical integer strings must coerce to integer keys. Authentication proves key possession, not that the bytes came from phpser's encoder: a key holder can sign a handcrafted frame. TAG_ASSOC therefore always uses update semantics; schema-based paths use add_new only after validating distinct, non-numeric keys once at schema read. 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. That step moved rowset_1000 encode to 25% faster than igbinary (up from 8% in the pre-upgrade implementation); the later columnar TAG_TABLE format and delta id columns took rowsets further still, to -45% size and -58% encode versus igbinary.

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

• The three entry points signal corrupt input differently. phpser_unserialize() returns null on malformed, truncated, or over-deep input — silently, and indistinguishably from a successfully-decoded null. Trailing bytes after a complete top-level value are tolerated on this path (prefix read). phpser_unserialize_signed() throws instead (since 0.4.0), so a legitimately-signed null still decodes cleanly, and both the signed and session paths require exact consumption of the frame. The session handler reports decode failure to the engine (warning; a scalar-root payload fails the read rather than becoming an empty session). When a cache miss must be told apart from a cached null, use the signed entry point. SECURITY.md carries the full contract.
• 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. This behavior differs from native serialize() by design: PHP throws when serializing a Closure and serializes a resource as its numeric resource id. phpser treats both as unsupported cache values and writes NULL.
• Unknown classes at decode become __PHP_Incomplete_Class with the original name preserved, matching PHP native unserialize(). This holds for plain objects and __serialize-based objects, and for any shape whose class the allowed_classes filter denies. Two wire shapes differ when the class is merely absent (rather than denied): a legacy Serializable value (TAG_OBJECT_LEGACY) whose class is gone decodes as null in place, and an enum (TAG_ENUM) whose class is gone fails the whole decode, because neither carries a property schema to install into. The positional DTO (TAG_OBJECT_SLOTS) decodes to an incomplete object that still claims its id for later back-refs; when its class is already loaded the values are installed onto the incomplete, and only when the class is unavailable are the unnamed slot values dropped (phpser does not autoload a class for the sole purpose of recovering property names). Evolve classes append-only if cached payloads must outlive a schema change.
• Enum cases are filtered by allowed_classes. Native unserialize() does not consult the allowlist on its enum path, so a serialized enum is always resurrected there. phpser applies the filter: a disallowed enum decodes to __PHP_Incomplete_Class. Enum cases are inert singletons, so the security delta is small, but list their class names in the allowlist if you rely on enums round-tripping through a filtered decode.
• Strings and blobs are capped at 4 GiB (UINT32_MAX) on the wire. Encoding a longer value fails loud (throws for the userland API, an E_WARNING for the session handler) rather than emitting bytes the decoder would reject. No single cache value realistically approaches this.
• Encode memory is O(distinct strings), uncapped. The encoder interns every distinct string it emits into a cache that grows without eviction for the duration of the call (pre-sized from the top-level value, so the common shapes never regrow mid-encode). A value with N unique strings holds N entries until the encode returns; nothing is retained between calls. Unusually string-diverse values cost temporary memory proportional to their diversity — chunk the value if that matters.
• Wire integers outside the target zend_long range are rejected on 32-bit builds. A payload written by a 64-bit process can carry values a 32-bit zend_long cannot hold. Decode returns null instead of narrowing them, so a cache shared between 32-bit and 64-bit processes has to stay inside the 32-bit range. This covers scalars, packed runs, table columns, and array keys; encoding is unaffected.
• TAG_OBJECT_SLOTS is positional. Eligible typed objects encode their declared properties as values in properties_info_table (declaration) order with no per-property names; decode installs them back in that order. An older payload carrying a prefix of the current effective slot table is accepted and appended properties retain their class defaults. A payload with more slots than the current class is rejected. Nothing else is detectable. The decoder cannot tell an append-at-end from an insertion or a reorder, so any other schema change silently lands values in the wrong slots, including a change that alters the slot count. Inserting $mid between $a and $b, for example, decodes an old two-slot payload as a=1, mid=2, b=<default> with no error. Type declarations catch only the subset of mismatches that fail a coercion. For payloads that outlive a deploy, append properties only at the end of the effective properties_info_table order. Adding a parent property can insert before child slots and break append-only order.
• 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. The handler serializes $_SESSION as a single phpser array value; it is not byte-compatible with the built-in php, php_binary, or igbinary session formats, so switching handlers doesn't read back sessions written by another. It also decodes with all classes allowed and magic methods enabled: treat the session store as trusted, exactly as with the native php_serialize handler. If session encode fails on coder limits (over-deep or oversized input), the handler persists a 29-byte phpser:session-not- serialized tombstone marker instead of the session, so the next read fails loudly (engine warning, session destroyed) rather than silently resuming an empty session. Only a user-hook throw during encode persists nothing, matching the never-persist-on-hook-failure rule.

Wire format (V1 / V2)

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

The version byte is emitted as 0x02 only when the body actually uses a v2-only tag (0x12–0x17); otherwise it stays 0x01. On decode it is a minimum-reader signal, not a gate: the tag dispatch is version-agnostic, so a hand-built frame carrying a v2 tag under a 0x01 header still decodes. This tolerance keeps the version byte additive. Don't rely on it alone to reject a future format; a backwards-incompatible change gets a new version constant and explicit tag rejection.

🔗 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.
• fastjson: drop-in faster ext/json, backed by yyjson. 6× encode, 2.7× decode, 5× validate.
• 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.

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