Modernize for 4.0.0: PHP 8.1+, full typing, PHPUnit 10-12, GitHub Actions

.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+
+jobs:
+  tests:
+    name: Tests (PHP ${{ matrix.php }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        php:
+          - '8.1'
+          - '8.2'
+          - '8.3'
+          - '8.4'
+          - '8.5'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          coverage: none
+
+      - name: Install dependencies
+        run: composer update --no-interaction --no-progress --prefer-dist
+
+      - name: Run tests
+        run: vendor/bin/phpunit
+
+  checks:
+    name: Coding standards & static analysis
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.3'
+          coverage: none
+
+      - name: Install dependencies
+        run: composer update --no-interaction --no-progress --prefer-dist
+
+      - name: Check coding standards
+        run: vendor/bin/phpcs
+
+      - name: Run static analysis
+        run: vendor/bin/phpstan analyse --no-progress
+
+      - name: Check automated refactoring (Rector)
+        run: vendor/bin/rector --dry-run --no-progress-bar

.gitignore

@@ -1 +1,6 @@
 /vendor/
+/composer.lock
+/.phpunit.cache/
+/.phpunit.result.cache
+/.phpcs-cache
+/clover.xml

CHANGELOG.md

@@ -5,6 +5,54 @@ which adheres to the guidelines at http://keepachangelog.com/.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
+
+## [4.0.0] - 2026-08-14
+Hash values and position derivation are unchanged: upgrading does **not**
+remap keys to different targets.
+
+### Added
+- GitHub Actions CI, testing PHP 8.1 through 8.5.
+- Static analysis with PHPStan (level 9).
+- Automated refactoring with Rector, with PHP sets derived from the
+  supported PHP floor in composer.json.
+- Full parameter, return, and property type declarations throughout.
+- Composer scripts: `test`, `benchmark`, `cs`, `cs:fix`, `stan`, `check`.
+- Regression tests for `lookupList()` with duplicate adjacent ring positions.
+
+### Changed
+- **BC break:** PHP 8.1 minimum (was 7.2).
+- **BC break:** `HasherInterface::hash()` is now declared as
+  `hash(string $string): int|float`. Custom hasher implementations must add
+  a compatible return type declaration.
+- **BC break:** `Flexihash` methods now declare parameter types
+  (e.g. `addTarget(string $target, int|float $weight = 1)`). Callers in
+  `strict_types` files passing non-string targets must cast them.
+- **BC break:** `lookupList()` now also rejects negative counts
+  (previously only zero was rejected).
+- Coding standard upgraded from PSR-2 to PSR-12.
+- PHPUnit upgraded from 8 to 10/11/12.
+
+### Fixed
+- `lookupList()` could return fewer targets than requested when adjacent
+  positions on the ring belonged to the same target: duplicates are now
+  skipped instead of being counted towards the requested number. This was
+  a regression in the unreleased binary-search lookup (#24); released
+  versions are not affected.
+- Deprecation warning on PHP 8.4 due to the implicitly nullable
+  constructor parameters (`Flexihash::__construct()`).
+- `BenchmarkTest::median()` picked the wrong elements for even-sized data
+  sets and could fail with a `TypeError` under `strict_types`.
+
+### Removed
+- Travis CI and Coveralls integration (replaced by GitHub Actions).
+- The committed `composer.lock` (libraries should resolve dependencies fresh).
+
+## [3.0.0] - 2020-08-07
+### Changed
+- PHP 7.2 minimum.
+- PHPUnit 8.
+- Enable strict typing mode for all PHP files.
+
 ## [2.0.2] - 2016-04-22
 ### Changed
 - Pinned symfony component version to pass tests on 5.4.x.
@@ -48,7 +96,9 @@ due to PHP treating numeric string array keys as integers.
 Posterity release
 
 
-[Unreleased]: https://github.com/pda/flexihash/compare/v2.0.2...master
+[Unreleased]: https://github.com/pda/flexihash/compare/v4.0.0...master
+[4.0.0]: https://github.com/pda/flexihash/compare/v3.0.0...v4.0.0
+[3.0.0]: https://github.com/pda/flexihash/compare/v2.0.2...v3.0.0
 [2.0.2]: https://github.com/pda/flexihash/compare/v2.0.1...v2.0.2
 [2.0.1]: https://github.com/pda/flexihash/compare/v2.0.0...v2.0.1
 [2.0.0]: https://github.com/pda/flexihash/compare/v1.0.0...v2.0.0

README.md

@@ -1,27 +1,43 @@
 # Flexihash
 
-[![Build Status](https://travis-ci.org/pda/flexihash.svg?branch=master)](https://travis-ci.org/pda/flexihash) [![Coverage Status](https://coveralls.io/repos/github/pda/flexihash/badge.svg?branch=master)](https://coveralls.io/github/pda/flexihash?branch=master)
+[![CI](https://github.com/pda/flexihash/actions/workflows/ci.yml/badge.svg)](https://github.com/pda/flexihash/actions/workflows/ci.yml)
 
-Flexihash is a small PHP library which implements [consistent hashing](http://en.wikipedia.org/wiki/Consistent_hashing), which is most useful in distributed caching. It requires PHP5 and uses [PHPUnit](http://simpletest.org/) for unit testing.
+Flexihash is a small PHP library which implements [consistent hashing](https://en.wikipedia.org/wiki/Consistent_hashing), which is most useful in distributed caching.
+
+## Requirements
+
+Flexihash 4.x requires PHP 8.1 or later, and has no other dependencies.
+Older releases remain available for older PHP versions:
+
+| Flexihash | PHP        |
+|-----------|------------|
+| 4.x       | >= 8.1     |
+| 3.x       | >= 7.2     |
+| 2.x       | >= 5.4     |
 
 ## Installation
 
 [Composer](https://getcomposer.org/) is the recommended installation technique. You can find flexihash on [Packagist](https://packagist.org/packages/flexihash/flexihash) so installation is as easy as
+
 ```
 composer require flexihash/flexihash
 ```
+
 or in your `composer.json`
+
 ```json
 {
     "require": {
-        "flexihash/flexihash": "^3.0.0"
+        "flexihash/flexihash": "^4.0"
     }
 }
 ```
 
 ## Usage
 
 ```php
+use Flexihash\Flexihash;
+
 $hash = new Flexihash();
 
 // bulk add
@@ -44,21 +60,35 @@ $hash->removeTarget('cache-2');
 $hash->lookup('object'); // "cache-4"
 ```
 
-## Tests
+The hash algorithm (CRC32 by default) and the number of replicas
+(64 by default) can be configured on construction:
 
-### Unit Test
+```php
+use Flexihash\Flexihash;
+use Flexihash\Hasher\Md5Hasher;
 
-```
-% vendor/bin/phpunit
+$hash = new Flexihash(new Md5Hasher(), 128);
 ```
 
-### Benchmark Test
+Custom hash algorithms can be used by implementing
+`Flexihash\Hasher\HasherInterface`.
+
+## Development
 
 ```
-% vendor/bin/phpunit tests/BenchmarkTest.php
+composer install
 ```
 
+| Command              | Description                                        |
+|----------------------|----------------------------------------------------|
+| `composer test`      | Run the unit test suite (PHPUnit)                  |
+| `composer cs`        | Check coding standards (PSR-12)                    |
+| `composer stan`      | Run static analysis (PHPStan)                      |
+| `composer rector`    | Check for automated refactorings (Rector, dry-run) |
+| `composer check`     | Run all of the above                               |
+| `composer benchmark` | Run the benchmark suite                            |
+
 ## Further Reading
 
-  * http://www.spiteful.com/2008/03/17/programmers-toolbox-part-3-consistent-hashing/
-  * http://weblogs.java.net/blog/tomwhite/archive/2007/11/consistent_hash.html
+  * https://www.spiteful.com/2008/03/17/programmers-toolbox-part-3-consistent-hashing/
+  * https://web.archive.org/web/20120605030524/http://weblogs.java.net/blog/tomwhite/archive/2007/11/consistent_hash.html

ROADMAP.md

@@ -1,4 +1,4 @@
-#Roadmap
+# Roadmap
 
 ## v1.0.0
 
@@ -26,5 +26,9 @@ The historical API will be broken by classname changes.
 
 ## v4.0.0
 
-- [ ] PHP 7.3 minimum.
-- [ ] PHPUnit 9.
+- [x] PHP 8.1 minimum.
+- [x] Full parameter, return and property type declarations.
+- [x] PHPUnit 10/11/12.
+- [x] PSR-12 coding standard.
+- [x] Static analysis with PHPStan.
+- [x] GitHub Actions CI (replacing Travis CI).

composer.json

@@ -2,13 +2,14 @@
     "name": "flexihash/flexihash",
     "type": "library",
     "description": "Flexihash is a small PHP library which implements consistent hashing",
+    "keywords": ["hashing", "consistent-hashing", "consistent", "hash", "distributed", "caching"],
     "homepage": "https://github.com/pda/flexihash",
     "license": "MIT",
     "authors": [
         {
             "name": "Paul Annesley",
             "email": "[email protected]",
-            "homepage": "http://paul.annesley.cc"
+            "homepage": "https://paul.annesley.cc"
         },
         {
             "name": "Dom Morgan",
@@ -17,17 +18,13 @@
         }
     ],
     "require": {
-        "php": ">=7.2.0"
+        "php": "^8.1"
     },
     "require-dev": {
-        "phpunit/phpunit": "^8",
-        "squizlabs/php_codesniffer": "3.*",
-        "php-coveralls/php-coveralls": "^2.2",
-        "symfony/config": "^5.1.3",
-        "symfony/console": "^5.1.3",
-        "symfony/filesystem": "^5.1.3",
-        "symfony/stopwatch": "^5.1.3",
-        "symfony/yaml": "^5.1.3"
+        "phpstan/phpstan": "^2.1",
+        "phpunit/phpunit": "^10.5 || ^11.5 || ^12.0",
+        "rector/rector": "^2.1",
+        "squizlabs/php_codesniffer": "^3.13"
     },
     "autoload": {
         "psr-4": {
@@ -38,5 +35,33 @@
         "psr-4": {
             "Flexihash\\Tests\\": "tests/"
         }
+    },
+    "scripts": {
+        "test": "phpunit",
+        "benchmark": "phpunit --group benchmark tests/BenchmarkTest.php",
+        "cs": "phpcs",
+        "cs:fix": "phpcbf",
+        "stan": "phpstan analyse --no-progress",
+        "rector": "rector --dry-run",
+        "rector:fix": "rector",
+        "check": [
+            "@cs",
+            "@stan",
+            "@rector",
+            "@test"
+        ]
+    },
+    "scripts-descriptions": {
+        "test": "Run the unit test suite",
+        "benchmark": "Run the benchmark suite",
+        "cs": "Check coding standards (PSR-12)",
+        "cs:fix": "Fix coding standard violations",
+        "stan": "Run static analysis",
+        "rector": "Check for automated refactoring opportunities (dry-run)",
+        "rector:fix": "Apply automated refactorings",
+        "check": "Run all checks (coding standards, static analysis, rector, tests)"
+    },
+    "config": {
+        "sort-packages": true
     }
 }