PHPackages                             orieg/judy - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. orieg/judy

ActivePhp-ext

orieg/judy
==========

PHP Judy implements sparse dynamic arrays (aka Judy Arrays).

v2.4.0(2mo ago)7423↑76.5%11PHP-3.01PHPPHP >=8.0.0CI passing

Since Aug 25Pushed 2mo ago6 watchersCompare

[ Source](https://github.com/orieg/php-judy)[ Packagist](https://packagist.org/packages/orieg/judy)[ Docs](https://github.com/orieg/php-judy)[ RSS](/packages/orieg-judy/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (3)DependenciesVersions (33)Used By (0)

PHP Judy
========

[](#php-judy)

**PHP Judy** - Extension for creating and accessing dynamic arrays

[![PECL](https://camo.githubusercontent.com/aa089e9a553f8a1f53e261125465c6ddb237d22567784b52ecc9ddd4dda7c9be/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5045434c2d4a7564792d626c75652e737667)](https://pecl.php.net/package/Judy)[![Packagist](https://camo.githubusercontent.com/6a9d884b5dd622a1f141765a6317339f2237267a52c86dab09abcfaeb0e569ed/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5061636b61676973742d6f726965672f6a7564792d6f72616e67652e737667)](https://packagist.org/packages/orieg/judy)[![PHP Version](https://camo.githubusercontent.com/7b973e18e5dc1eee6a0177db2c17f4e9fb66e3ac54b64909426e8dfa482aed61/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e302b2d677265656e2e737667)](https://php.net)[![License](https://camo.githubusercontent.com/38827cec694673d3063702bbcbde80d0e4f080c0ed4e7b91896f471f4422d069/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d5048502d626c75652e737667)](LICENSE)

Table of Contents
-----------------

[](#table-of-contents)

1. [Introduction](#introduction)
2. [Directory Contents](#directory-contents)
3. [Installation](#installation)
4. [Usage Examples](#usage-examples)
5. [Reporting Bugs](#reporting-bugs)
6. [Roadmap](#roadmap)

Introduction
------------

[](#introduction)

**php-judy** is an extension by Nicolas Brousse for the Judy C library. It is compatible with PHP 8.0 and newer.

- **PECL Package**:
- **Packagist Package**:
- **GitHub Repository**:

A Judy array is a complex but very fast associative array data structure for storing and looking up values using integer or string keys. Unlike normal arrays, Judy arrays may be sparse; that is, they may have large ranges of unassigned indices.

- **Wikipedia**: [http://en.wikipedia.org/wiki/Judy\_array](http://en.wikipedia.org/wiki/Judy_array)

The PHP extension is based on the Judy C library that implements a dynamic array. A Judy array consumes memory only when populated yet can grow to take advantage of all available memory. Judy's key benefits are: scalability, performance, memory efficiency, and ease of use. Judy arrays are designed to grow without tuning into the peta-element range, scaling near O(log-base-256) -- 1 more RAM access at 256 X population.

- **Judy C Library**:

For a detailed performance comparison with native PHP arrays, please see the [BENCHMARK.md](BENCHMARK.md) file.

Directory Contents
------------------

[](#directory-contents)

```
README.md            This file
API.md               Complete API reference
BENCHMARK.md         Performance benchmarks and analysis
MIGRATION_2.2.0.md   Migration guide for version 2.2.0
LICENSE              The PHP License used by this project

tests/               Unit tests (176 tests)
examples/            Benchmark and example scripts
libjudy/             Bundled libJudy
*.c, *.h             C source and header files
Judy.stub.php        PHP stub for IDE autocompletion

```

Installation
------------

[](#installation)

### A. Using PHP PIE (Recommended)

[](#a-using-php-pie-recommended)

PHP PIE (PHP Extension Installer) is the easiest way to install PHP Judy on supported platforms:

```
# Install PHP PIE if you don't have it
curl -sSL https://pie.dev/installer | php

# Install PHP Judy using PIE
pie install judy
```

**Note**: PHP PIE automatically handles dependencies and builds the extension for your specific PHP version and platform.

### B. Using PECL

[](#b-using-pecl)

You can also install PHP Judy using PECL:

```
# Install the extension with pecl
pecl install judy
```

**Note**: You may need to install the Judy C library first on some systems.

### C. Linux (Manual Build)

[](#c-linux-manual-build)

From the PHP Judy sources:

```
phpize
./configure --with-judy[=DIR]
make
make test
make install
```

If you are using Ubuntu or Debian, you can install libJudy with apt:

```
apt-get install libjudydebian1 libjudy-dev
phpize
./configure --with-judy=/usr
make
make test
make install
```

### D. Windows

[](#d-windows)

On Windows, you will need to build LibJudy yourself.

Download the sources at

Extract the sources, and open the Visual Studio command prompt and navigate to the source directory. Then execute:

```
build

```

This creates "Judy.lib", copy this into the php-sdk library folder and name it `libJudy.lib`

Then copy the include file "judy.h" into the php-sdk includes folder. Now it's time to build pecl/judy, extract the pecl/judy into your build folder where the build scripts will be able to pick it up, e.g.:

```
C:\php\pecl\judy\

```

If your source of PHP is located in:

```
C:\php\src\

```

The rest of the steps is pretty straightforward, like any other external extension:

```
buildconf
configure --with-judy=shared
nmake
```

### E. Mac OS X

[](#e-mac-os-x)

The recommended way to install `php-judy` on Mac OS X is by using `pie` or `pecl`. You will need to have the Judy C library installed first, which can be done easily with Homebrew.

#### Using PHP PIE (Recommended)

[](#using-php-pie-recommended)

```
# Install PHP PIE if you don't have it
curl -sSL https://pie.dev/installer | php

# Install PHP Judy using PIE
pie install judy
```

#### Using PECL

[](#using-pecl)

```
# First, install the Judy C library
brew install judy

# Then, install the extension with pecl
pecl install judy
```

#### Manual Install

[](#manual-install)

If you prefer to compile from source, you will need to install the libJudy first. Download the sources at

Extract the sources, then cd into the source directory and execute:

```
./configure
make
make install
```

Usage Examples
--------------

[](#usage-examples)

Judy arrays can be used like usual PHP arrays. The difference will be in the type of key/values that you can use. Judy arrays are optimized for memory usage but it forces some limitations in the PHP API.

There are 10 types of PHP Judy Arrays, organized into three families:

### Integer-Keyed Types

[](#integer-keyed-types)

#### 1. Judy::BITSET

[](#1-judybitset)

A Judy array with only 1 bit per index. It can be used to store boolean values.

```
$judy = new Judy(Judy::BITSET);
$judy[100] = true;
$judy[200] = true;
$judy[300] = false;

if ($judy[100]) {
    echo "Index 100 is set\n";
}
```

#### 2. Judy::INT\_TO\_INT

[](#2-judyint_to_int)

A Judy array with integer keys and integer values.

```
$judy = new Judy(Judy::INT_TO_INT);
$judy[1] = 100;
$judy[2] = 200;
$judy[3] = 300;

echo $judy[2]; // Outputs: 200
```

#### 3. Judy::INT\_TO\_MIXED

[](#3-judyint_to_mixed)

A Judy array with integer keys and mixed values (strings, integers, etc.).

```
$judy = new Judy(Judy::INT_TO_MIXED);
$judy[1] = "Hello";
$judy[2] = 42;
$judy[3] = [1, 2, 3];

echo $judy[1]; // Outputs: Hello
```

#### 4. Judy::INT\_TO\_PACKED

[](#4-judyint_to_packed)

A Judy array with integer keys and serialized ("packed") values. Values are stored as opaque byte buffers outside PHP's garbage collector using `php_var_serialize`/`php_var_unserialize`. This trades serialize/deserialize CPU cost for reduced GC pressure, making it suitable for large datasets where GC pauses are a concern.

Supports any serializable PHP value (strings, integers, floats, arrays, objects). Closures and generators cannot be stored.

```
$judy = new Judy(Judy::INT_TO_PACKED);
$judy[0] = "Hello";
$judy[1] = 42;
$judy[2] = [1, 2, 3];
$judy[3] = new DateTimeImmutable();

echo $judy[0]; // Outputs: Hello
// Values are fully reconstructed on read
$arr = $judy[2]; // Returns [1, 2, 3]
```

**When to use INT\_TO\_PACKED vs INT\_TO\_MIXED:**

- Use `INT_TO_MIXED` for small-to-medium arrays or when read/write speed is critical
- Use `INT_TO_PACKED` for large arrays (100K+ elements) where GC pause reduction matters more than individual read/write latency

### String-Keyed Types (Trie-Based)

[](#string-keyed-types-trie-based)

Trie-based types use JudySL internally. Keys are stored in sorted lexicographic order, making iteration ordered and range queries efficient. Lookup is O(key-length).

#### 5. Judy::STRING\_TO\_INT

[](#5-judystring_to_int)

A Judy array with string keys and integer values.

```
$judy = new Judy(Judy::STRING_TO_INT);
$judy["apple"] = 1;
$judy["banana"] = 2;
$judy["cherry"] = 3;

echo $judy["banana"]; // Outputs: 2
```

#### 6. Judy::STRING\_TO\_MIXED

[](#6-judystring_to_mixed)

A Judy array with string keys and mixed values.

```
$judy = new Judy(Judy::STRING_TO_MIXED);
$judy["name"] = "John Doe";
$judy["age"] = 30;
$judy["scores"] = [85, 92, 78];

echo $judy["name"]; // Outputs: John Doe
```

### String-Keyed Types (Hash-Based)

[](#string-keyed-types-hash-based)

Hash-based types use JudyHS for O(1) average-case lookups, with a parallel JudySL key index that maintains sorted iteration order. Best for workloads dominated by random key access where you still need ordered iteration.

#### 7. Judy::STRING\_TO\_INT\_HASH

[](#7-judystring_to_int_hash)

A hash-backed Judy array with string keys and integer values.

```
$judy = new Judy(Judy::STRING_TO_INT_HASH);
$judy["session_abc"] = 1;
$judy["session_xyz"] = 2;

echo $judy["session_abc"]; // Outputs: 1

// Iteration is still sorted (via the key index)
foreach ($judy as $key => $value) {
    echo "$key => $value\n";
}
```

#### 8. Judy::STRING\_TO\_MIXED\_HASH

[](#8-judystring_to_mixed_hash)

A hash-backed Judy array with string keys and mixed values.

```
$judy = new Judy(Judy::STRING_TO_MIXED_HASH);
$judy["config_a"] = ["enabled" => true];
$judy["config_b"] = 42;
```

### String-Keyed Types (Adaptive / SSO)

[](#string-keyed-types-adaptive--sso)

Adaptive types use Short-String Optimization (SSO): keys of 7 bytes or fewer are packed into a 64-bit integer and stored in a JudyL array, avoiding hashing overhead entirely. Longer keys fall back to JudyHS. A JudySL key index maintains sorted iteration. Best for mixed-length key workloads with many short keys.

#### 9. Judy::STRING\_TO\_INT\_ADAPTIVE

[](#9-judystring_to_int_adaptive)

An adaptive Judy array with string keys and integer values.

```
$judy = new Judy(Judy::STRING_TO_INT_ADAPTIVE);
$judy["us"] = 1;       // SSO: packed into JudyL (2 bytes)
$judy["uk"] = 2;       // SSO: packed into JudyL (2 bytes)
$judy["a_very_long_country_name"] = 3;  // Falls back to JudyHS
echo $judy["us"]; // Outputs: 1
```

#### 10. Judy::STRING\_TO\_MIXED\_ADAPTIVE

[](#10-judystring_to_mixed_adaptive)

An adaptive Judy array with string keys and mixed values.

```
$judy = new Judy(Judy::STRING_TO_MIXED_ADAPTIVE);
$judy["id"] = 12345;
$judy["name"] = "Alice";
$judy["metadata"] = ["role" => "admin"];
```

### Iterator Interface (PHP 8+)

[](#iterator-interface-php-8)

Judy arrays implement the PHP Iterator interface, allowing you to use them in foreach loops:

```
$judy = new Judy(Judy::INT_TO_MIXED);
$judy[1] = "First";
$judy[5] = "Fifth";
$judy[10] = "Tenth";

// Iterate through all elements
foreach ($judy as $key => $value) {
    echo "Key: $key, Value: $value\n";
}

// Manual iteration
$judy->rewind();
while ($judy->valid()) {
    $key = $judy->key();
    $value = $judy->current();
    echo "Key: $key, Value: $value\n";
    $judy->next();
}
```

### Performance Considerations

[](#performance-considerations)

- **Memory Efficiency**: Judy arrays use 2-4x less memory than PHP arrays
- **Sequential Access**: Excellent performance for ordered iteration
- **Range Queries**: Native support via `slice()`, `deleteRange()`, and `populationCount()`
- **Random Access**: Trie types are slower than PHP arrays (O(log n) vs O(1)); Hash types offer O(1) average-case lookups for string keys
- **String Lookups**: Use `STRING_TO_*_HASH` or `STRING_TO_*_ADAPTIVE` types for faster string key access when sorted traversal is not the primary use case

### Batch Operations and Conversion

[](#batch-operations-and-conversion)

Judy arrays provide batch methods for efficient bulk operations:

```
// Convert a PHP array to a Judy array
$judy = Judy::fromArray(Judy::INT_TO_INT, [0 => 100, 5 => 200, 10 => 300]);

// Convert a Judy array back to a PHP array
$arr = $judy->toArray(); // [0 => 100, 5 => 200, 10 => 300]

// Bulk-insert from an existing array
$judy->putAll([20 => 400, 30 => 500]);

// Retrieve multiple values at once (missing keys return null)
$values = $judy->getAll([0, 5, 99]); // [0 => 100, 5 => 200, 99 => null]
```

### Atomic Increment

[](#atomic-increment)

For `INT_TO_INT`, `STRING_TO_INT`, and `STRING_TO_INT_HASH` types, `increment()` performs an efficient counter update:

```
$counters = new Judy(Judy::STRING_TO_INT);

// Increment creates the key with the given amount if it doesn't exist
$counters->increment("page_views");       // returns 1
$counters->increment("page_views");       // returns 2
$counters->increment("page_views", 10);   // returns 12
$counters->increment("page_views", -3);   // returns 9
```

For detailed performance analysis, see [BENCHMARK.md](BENCHMARK.md).

### Expanded API

[](#expanded-api)

Beyond basic array access, Judy provides a rich API including:

- **Set operations**: `union()`, `intersect()`, `diff()`, `xor()`, `mergeWith()`
- **Functional iteration**: `forEach()`, `filter()`, `map()` (C-level, bypasses Iterator overhead)
- **Range operations**: `slice()`, `deleteRange()`, `populationCount()`
- **Aggregation**: `sumValues()`, `averageValues()`
- **Batch operations**: `putAll()`, `getAll()`, `keys()`, `values()`, `toArray()`, `fromArray()`
- **Serialization**: `serialize()`/`unserialize()`, `json_encode()`
- **Comparison**: `equals()`

For complete method signatures, parameter details, and type compatibility, see [API.md](API.md).

Reporting Bugs
--------------

[](#reporting-bugs)

Please report bugs and issues on the GitHub repository:

Roadmap
-------

[](#roadmap)

- Eliminate redundant JLG+JLI double traversal in write hot paths for MIXED/PACKED types
- C-level `forEach()`/`filter()`/`map()` performance tuning (vtable dispatch)
- Binary serialization format for faster `__serialize`/`__unserialize`
- Extend set operations (`union`/`intersect`/`diff`/`xor`) to adaptive types
- Extend `increment()` to adaptive types

License
-------

[](#license)

This project is licensed under the PHP License - see the [LICENSE](LICENSE) file for details.

Contributing
------------

[](#contributing)

Contributions are welcome! Please feel free to submit a Pull Request.

Support
-------

[](#support)

- **API Reference**: [API.md](API.md) for complete method documentation
- **Benchmarks**: [BENCHMARK.md](BENCHMARK.md) for performance analysis
- **Migration Guide**: [MIGRATION\_2.2.0.md](MIGRATION_2.2.0.md) for version 2.2.0 changes
- **Examples**: Check the `examples/` directory for usage examples

###  Health Score

47

—

FairBetter than 94% of packages

Maintenance86

Actively maintained with recent releases

Popularity24

Limited adoption so far

Community20

Small or concentrated contributor base

Maturity52

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 88.9% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~95 days

Total

3

Last Release

68d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/712880f4812bfa5d4d9494295cfc4d360509e933fe3036435344eac81047063e?d=identicon)[orieg](/maintainers/orieg)

---

Top Contributors

[![orieg](https://avatars.githubusercontent.com/u/55721?v=4)](https://github.com/orieg "orieg (295 commits)")[![tony2001](https://avatars.githubusercontent.com/u/42386?v=4)](https://github.com/tony2001 "tony2001 (22 commits)")[![Sannis](https://avatars.githubusercontent.com/u/77367?v=4)](https://github.com/Sannis "Sannis (8 commits)")[![weltling](https://avatars.githubusercontent.com/u/22016?v=4)](https://github.com/weltling "weltling (2 commits)")[![jeremyFreeAgent](https://avatars.githubusercontent.com/u/176363?v=4)](https://github.com/jeremyFreeAgent "jeremyFreeAgent (2 commits)")[![remicollet](https://avatars.githubusercontent.com/u/270445?v=4)](https://github.com/remicollet "remicollet (1 commits)")[![noobpwnftw](https://avatars.githubusercontent.com/u/10750762?v=4)](https://github.com/noobpwnftw "noobpwnftw (1 commits)")[![cesaredamico](https://avatars.githubusercontent.com/u/202101?v=4)](https://github.com/cesaredamico "cesaredamico (1 commits)")

---

Tags

extensionjudy-arraysmemoryperformance-optimizationphpphp8sparse-arrays

### Embed Badge

![Health badge](/badges/orieg-judy/health.svg)

```
[![Health](https://phpackages.com/badges/orieg-judy/health.svg)](https://phpackages.com/packages/orieg-judy)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)