esi/consistent-hash

ConsistentHash is a small library which implements consistent hashing. Modernized fork of flexihash/flexihash.

1.1.0 2024-12-10 06:57 UTC

Requires

• php: ^8.2
• ext-hash: *

Requires (Dev)

• esi/phpunit-coverage-check: ^2.0
• friendsofphp/php-cs-fixer: ^3.65
• phpbench/phpbench: ^1.3
• phpstan/extension-installer: ^1.4
• phpstan/phpstan: ^2.0
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-phpunit: ^2.0
• phpstan/phpstan-strict-rules: ^2.0
• phpunit/phpunit: ^11.5
• psalm/plugin-phpunit: ^0.19.0
• vimeo/psalm: dev-master

MIT

• Eric Sizemore
• Paul Annesley
• Dom Morgan

• php
• hash
• consistent
• consistent-hash
• consistent-hashing

README

Esi\ConsistentHash is a small PHP library which implements consistent hashing, which is most useful in distributed caching.

Note

This library is a fork of https://github.com/pda/flexihash v3.0.0. The original library has not seen any releases since 2020.

Installation

You can install the package via composer:

$ composer require esi/consistent-hash

Usage

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"

Benchmarks

PHPBench

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

PHPUnit

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

$ composer run-script phpunit:benchmark

About

Requirements

• PHP >= 8.2

Credits

• Eric Sizemore
• All Contributors
• Special thanks to JetBrains for their Licenses for Open Source Development

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

• Paul Annesley
• Dom Morgan
• All flexihash Contributors

Contributing

See CONTRIBUTING.

Bugs and feature requests are tracked on GitHub.

Contributor Covenant Code of Conduct

See CODE_OF_CONDUCT.md

Backward Compatibility Promise

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

Changelog

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

License

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

Roadmap/TODO

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

Security

See SECURITY for more information on the security disclosure process.