'Consistent Hash' is a small PHP library, which implements consistent hashing, which is most useful in distributed caching.

You can install the package via composer:

$ composer require esi/consistent-hash

use Esi\ConsistentHash;

$hash = new ConsistentHash();

// bulk add
$hash->addTargets(['cache-1', 'cache-2', 'cache-3']);

// simple lookup
$hash->lookup('object-a'); // "cache-1"
$hash->lookup('object-b'); // "cache-2"

// add and remove
$hash->addTarget('cache-4');
$hash->removeTarget('cache-1');

// lookup with next-best fallback (for redundant writes)
$hash->lookupList('object', 2); // ["cache-2", "cache-4"]

// remove cache-2, expect object to hash to cache-4
$hash->removeTarget('cache-2');
$hash->lookup('object'); // "cache-4"

Performance can be tested with PHPBench.

$ git clone https://github.com/ericsizemore/consistent-hash.git
$ cd consistent-hash
$ ./vendor/bin/phpbench run --report=aggregate --iterations=4 --tag=branch_main

Or via composer:

$ composer run-script benchmark

There is also an option to view results as a bar chart:

$ composer run-script benchmark:chart

With opcache enabled:

# Normal, aggregate report
$ composer run-script benchmark:opcache

# Bar chart
$ composer run-script benchmark:chart:opcache

Benchmarks are also available through PHPUnit, though it is a bit more rudimentary. To see these benchmarks, run:

$ composer run-script phpunit:benchmark

• PHP >= 8.3

• Eric Sizemore
• All Contributors

And thanks to the library this is a fork of, flexihash/flexihash:

• Paul Annesley
• Dom Morgan
• All flexihash Contributors

See CONTRIBUTING.

Bugs and feature requests are tracked on GitHub.

See CODE_OF_CONDUCT.md

See backward-compatibility.md for more information on Backwards Compatibility.

See the CHANGELOG for more information on what has changed recently.

See the LICENSE for more information on the license that applies to this project.

See the ROADMAP for more information what is currently being planned.

See SECURITY for more information on the security disclosure process.