judy-polyfill — Pure-PHP Drop-In Polyfill for PHP Judy Arrays

Core Capabilities

Designed to allow libraries and applications to use Judy data structures everywhere without compilation barriers.

💯

100% API Parity

Full implementation of all 11 Judy types (including Judy::STRING_TO_ENTRY), exact method signatures, error messages, and exception types.

🔍

1,700+ Verified Assertions

Tested continuously in CI against native ext-judy across PHP 8.1, 8.2, 8.3, 8.4, and 8.5 with 0 divergences.

🔒

Native TTL Cache Support

Implements all v2.7.0 cache methods: set(), get(), pruneExpired(), getEntry(), getExpiry(), and getFlags().

📦

Zero Dependencies

Lightweight single-class implementation with zero external packages. Requires only standard php >= 8.1.

🔄

Transparent Fallback

Auto-loads only when ext-judy is absent. When the C extension is installed, the native module executes with zero polyfill overhead.

🔀

Dual-Mode Library Friendly

Libraries can depend on orieg/judy-polyfill in require and suggest ext-judy for production speedups.

Code Showcase

Code patterns demonstrating pure-PHP execution matching ext-judy exact behavior.

<?php
// Works identically whether ext-judy is installed or not
$judy = new Judy(Judy::INT_TO_MIXED);

$judy[101] = ['id' => 101, 'status' => 'active'];
$judy[202] = ['id' => 202, 'status' => 'pending'];

isset($judy[101]); // true
count($judy);     // 2

// Exact Iterator traversal
foreach ($judy as $k => $v) {
    var_dump($k, $v);
}

<?php
// Compound cache entry type support (v2.7.0)
$cache = new Judy(Judy::STRING_TO_ENTRY);

// Store entry with TTL seconds and 16-bit metadata flags
$cache->set('token:xyz', 'user_session_payload', $ttl = 300, $flags = 0x0002);

// Read back value and inspect metadata
$val = $cache->get('token:xyz', $expiresAt, $flags);

// Evict expired items
$evictedCount = $cache->pruneExpired();

<?php
$data = ['alpha' => 1, 'beta' => 2, 'gamma' => 3];
$j = Judy::fromArray(Judy::STRING_TO_INT, $data);

// Ordered seeks
$first = $j->first();            // "alpha"
$next  = $j->searchNext($first);   // "beta"

// Range extraction
$slice = $j->keys('alpha', 'beta'); // ['alpha', 'beta']

{
    "name": "your-org/your-package",
    "require": {
        "php": ">=8.1",
        "orieg/judy-polyfill": "^2.7.0"
    },
    "suggest": {
        "ext-judy": "Native C extension for maximum throughput (pie install orieg/judy)"
    }
}

Parity & Compatibility Matrix

Every method and edge case is checked against ext-judy in automated differential tests.

API Feature / Method	ext-judy (C)	judy-polyfill (Pure PHP)	Status
All 11 Type Constants (BITSET .. STRING_TO_ENTRY)	100%	100%	✔ Full Parity
ArrayAccess (offsetGet, offsetSet, offsetExists, offsetUnset)	Strict Type-Check	Strict Type-Check	✔ Full Parity
Range Navigation (first, last, searchNext, prev)	Lexicographic / Unsigned	Lexicographic / Unsigned	✔ Full Parity
TTL Cache Methods (set, get, pruneExpired, getEntry, getExpiry, getFlags)	Native in C	Native in PHP	✔ Full Parity
Bulk APIs (fromArray, toArray, putAll, getAll, keys, values, size)	Single-Pass C	Single-Pass PHP	✔ Full Parity
Exception Messages & Types (Embedded NUL, TypeErrors)	Exact Message	Exact Message	✔ Full Parity

Installation

Install via Composer in any PHP 8.1+ project.

Composer Setup

composer require orieg/judy-polyfill

The polyfill registers the Judy class automatically via Composer autoloading whenever ext-judy is not loaded.