PHP Judy - extension creating and accessing dynamic arrays ================================================================
- Directory Contents
- How to install
- Usage (Examples)
- Reporting Bugs
(see Section 4 of this document for PHP examples)
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.
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.
2. PHP JUDY TOP DIRECTORY CONTENTS:
README This file. LICENSE The PHP License used by this project. EXPERIMENTAL Note about the status of this package.
lib/ Header and source libraries used by the package.
libjudy/ Bundled libJudy.
tests/ Unit tests. *.c, *.h Header and source files used to build the package. *.php PHP test/examples scripts.
3. HOW TO INSTALL
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
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:
This creates "Judy.lib", copy this into the php-sdk library folder and name it
Then copy the include file "judy.h" into the php-sdk includes folder. Now its 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.:
If your source of PHP is located in:
The rest of the steps is pretty straight forward, like any other external extension:
buildconf configure --with-judy=shared nmake
C. Mac OS X
Install with Homebrew
Install Homebrew Package Manager http://brew.sh/
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
brew tap homebrew/dupes brew tap homebrew/versions brew tap homebrew/homebrew-php
Install PHP Judy
brew install php56-judy
Use pecl to install the PHP Judy extension :
sudo pecl -d preferred_state=beta install Judy
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
4. USAGE (EXAMPLES)
Judy's array can be used like usual PHP arrays. The difference will be in the type of key/values that you can use. Judy arrays are optimised for memory usage but it force to some limitation in the PHP API.
There is currently 5 type of PHP Judy Arrays :
- BITSET (using Judy1)
- INT_TO_INT (using JudyL)
- INT_TO_MIXED (using JudyL)
- STRING_TO_INT (using JudySL)
- STRING_TO_MIXED (using JudySL)
You can use foreach() and the PHP array notation on all PHP Judy arrays.
Bitset implementation is quite basic for now. It allow you to set a bunch of index setting the value to false will be the same than using unset().
$bitset = new Judy(Judy::BITSET); $bitset = true; print $bitset; // will print 1 $bitset = false; // is the same as unset($bitset)
This type let you create an array with key and value of integer, and integer only.
$int2int = new Judy(Judy::INT_TO_INT); $int2int = 17; print $int2int; // will print 17
This type let you create an array with key as integer and value of any type, including other judy array or any object.
$int2mixed = new Judy(Judy::INT_TO_MIXED); $int2mixed = "one"; $int2mixed = array('a', 'b', 'c'); $int2mixed = new Judy(Judy::BITSET);
This type let you create an array with key as string (currently limited to 65536 char.) and an integer as the value.
$string2int = new Judy(Judy::STRING_TO_INT); $string2int["one"] = 1; $string2int["two"] = 2; print $string2int["one"]; // will print 1
This type let you create an array with key as string and values of any type, including other judy array or any objects.
$string2mixed = new Judy(Judy::STRING_TO_MIXED); $string2mixed["string"] = "hello world!"; $string2mixed["array"] = array('a', 'b', 'c'); $string2mixed["integer"] = 632; $string2mixed["bitset"] = new Judy(Judy::BITSET);
5. REPORTING BUGS
If you encounter a bug, please submit it via the bug tracker on Git Hub:
- Implements comparator and cast handler
- Add bitset comparator (cf. Judy1Op sample)