diff --git a/README.md b/README.md index 4746a44..259f95b 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ A Judy array consumes memory only when populated and scales near $O(\log_{256} N - **Dramatic Memory Savings**: Up to **21.9x less memory** than native PHP arrays for presence sets (`BITSET`), and **3.5–3.8x less memory** for sparse integer and string keys (measured as peak RSS). - **Native C Bulk Operations**: `toArray()`, `getAll()`, `keys()`, `values()`, and `fromArray()` run in native C up to **3.1x faster** than element-by-element PHP loops. - **Ordered Keys & Fast Slicing for Free**: Range queries, prefix invalidation (`keys($lo, $hi)`), and atomic updates (`increment()`) without hash-table sorting or full scans. -- **Dual-Engine Backing**: Bundles modernized **libJudy** (C, compiled by default) and fully supports **[Expanse](https://github.com/orieg/expanse)** (clean-room pure-Rust drop-in C ABI engine). +- **Dual-Engine Backing**: Bundles modernized **libJudy** (C, compiled by default) and fully supports **[Expanse](https://github.com/orieg/expanse)** (clean-room pure-Rust drop-in C ABI engine). Expanse also ships its own drop-in-compatible PHP packages — see [§G](#g-expanses-native-php-packages-drop-in-successor). - **Honest Trade-offs**: For random lookups on small dense datasets, native PHP arrays are faster. See [BENCHMARK.md](BENCHMARK.md) for full metrics and a decision guide. --- @@ -214,14 +214,18 @@ make ![Engine Performance Comparison](docs/assets/bench_engines.svg) -#### Linux (.deb package) +#### Linux (apt / dnf repositories) -Prebuilt packages are available on the [Expanse Releases page](https://github.com/orieg/expanse/releases): +Expanse publishes official apt and rpm repositories. The `libjudy-compat` package installs the system-wide `libJudy.so.1` symlinks and `libexpanse-dev` / `libexpanse-devel` ships `Judy.h`, so php-judy configures against `/usr` with no manual prefix: ```sh -# Download and install Expanse .deb (e.g. v0.2.0 for amd64) -curl -LO https://github.com/orieg/expanse/releases/download/v0.2.0/libexpanse_0.2.0_amd64.deb -sudo dpkg -i libexpanse_0.2.0_amd64.deb +# Debian / Ubuntu / Raspberry Pi OS (amd64, arm64, riscv64) +echo "deb [trusted=yes] https://orieg.github.io/expanse/apt/ stable main" | sudo tee /etc/apt/sources.list.d/expanse.list +sudo apt-get update && sudo apt-get install -y libexpanse1 libexpanse-dev libjudy-compat + +# RHEL / Fedora / Rocky / Amazon Linux (x86_64, aarch64, riscv64) +sudo dnf config-manager --add-repo https://orieg.github.io/expanse/rpm/expanse.repo +sudo dnf install -y libexpanse libexpanse-devel libjudy-compat # Compile php-judy against Expanse phpize @@ -231,12 +235,15 @@ make test sudo make install ``` +Individual `.deb` / `.rpm` files for each release are also attached to the [Expanse Releases page](https://github.com/orieg/expanse/releases). + #### Linux & macOS (Standalone Prefix or from Source) ```sh -# Option 1: Download prebuilt release tarball from https://github.com/orieg/expanse/releases -curl -LO https://github.com/orieg/expanse/releases/download/v0.2.0/expanse-0.2.0-x86_64-unknown-linux-gnu.tar.gz -tar -xzf expanse-0.2.0-x86_64-unknown-linux-gnu.tar.gz +# Option 1: Download a prebuilt release tarball from https://github.com/orieg/expanse/releases +# (substitute the current version, e.g. 0.4.1, and your target triple) +curl -LO https://github.com/orieg/expanse/releases/download/v/expanse--x86_64-unknown-linux-gnu.tar.gz +tar -xzf expanse--x86_64-unknown-linux-gnu.tar.gz # Option 2: Build expanse-capi from source with Cargo git clone https://github.com/orieg/expanse.git @@ -260,7 +267,7 @@ make test Unlike legacy C libjudy (which requires source code patches for 64-bit LLP64 `Word_t` and `PJERR`), Expanse natively supports 64-bit Windows without patching: ```powershell -# Extract expanse-v0.2.0-x86_64-pc-windows-msvc.zip (or build with cargo build --release -p expanse-capi) +# Extract expanse-v-x86_64-pc-windows-msvc.zip from the Releases page (or build with cargo build --release -p expanse-capi) # Setup prefix directory with include\Judy.h and lib\libJudy.lib $prefix = "C:\path\to\expanse-prefix" New-Item -ItemType Directory -Force -Path "$prefix\include", "$prefix\lib" @@ -275,6 +282,24 @@ configure --with-judy=C:\path\to\expanse-prefix nmake ``` +### G. Expanse's Native PHP Packages (Drop-in Successor) + +Beyond serving as php-judy's C engine (§F), Expanse ships its **own PHP packages**, designed for 1:1 `php-judy` class and constant compatibility (`Judy`, `Judy::BITSET`, `Judy::INT_TO_INT`, `Judy::STRING_TO_INT`, `ArrayAccess`, `byCount`) so existing call sites migrate unchanged: + +```sh +# Pure-PHP library (PSR-4): uses the native extension below when loaded, +# otherwise falls back to \FFI over libexpanse (no compiler required) +composer require orieg/expanse + +# Native Zend extension written in Rust, compiled locally by PIE (requires the Rust toolchain) +pie install orieg/expanse-extension +``` + +- **Stay on php-judy** for the mature C extension (`pie install orieg/judy` / PECL), optionally backed by the Expanse engine via §F. +- **Move to `orieg/expanse`** for the Rust-native extension, the zero-compile FFI fallback, and the additional `Expanse\Set` / `Expanse\Map` APIs. + +Packages: [`orieg/expanse`](https://packagist.org/packages/orieg/expanse) · [`orieg/expanse-extension`](https://packagist.org/packages/orieg/expanse-extension) · Guide: [Expanse PHP bindings](https://github.com/orieg/expanse/blob/main/docs/bindings/php.md) + ## 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.