README

Deterministic SHA-256 fingerprinting and recursive canonical payload hashing for PHP 8.2+

Installation • Basic Hashing • Key Features • Release Gate • Changelog

Stable Fingerprint generates small, deterministic SHA-256 fingerprints for pre-prepared PHP payloads.

It recursively sorts associative keys, preserves list order, canonicalizes finite float values, encodes compact JSON, and returns either a hexadecimal or raw binary SHA-256 digest. It deliberately avoids object normalization and business-specific data cleanup.

Key Features

Deterministic Payload Hashing: Generates consistent 64-character hex (hash()) or 32-byte binary (binary()) SHA-256 digests.
Recursive Key Sorting: Normalizes associative arrays with byte-wise SORT_STRING key ordering regardless of initial key sequence.
List Order Preservation: Preserves exact sequence for sequential indexed lists (0..n-1).
Finite Float Canonicalization: Accurately normalizes finite floats while rejecting non-finite values (INF, NAN).
Strict Input Validation: Rejects objects, enums, resources, invalid UTF-8 byte sequences, and cyclic references via InvalidPayloadException.
Static Convenience API: Quick hashing with StableFingerprint::compute($payload).

Requirements

PHP: 8.2+ (tested on 8.2, 8.3, 8.4, 8.5)
Standard PHP Extensions: ext-hash, ext-json

Installation

Install the package via Composer:

composer require alex-kassel/stable-fingerprint

Usage

Basic Hashing

use AlexKassel\StableFingerprint\StableFingerprint;

$fingerprint = new StableFingerprint();

$payload = [
    'price' => 19.90,
    'available' => true,
    'variants' => [
        ['size' => 'M', 'stock' => 4],
        ['size' => 'L', 'stock' => 2],
    ],
];

$hex = $fingerprint->hash($payload);      // 64 lowercase hexadecimal characters
$binary = $fingerprint->binary($payload); // 32 raw bytes

assert($hex === bin2hex($binary));

Static Convenience Helper

use AlexKassel\StableFingerprint\StableFingerprint;

$hex = StableFingerprint::compute(['vendor' => 'audi', 'model' => 'q4']);

Testing

From the monorepo root, run the complete package verification pipeline:

composer pkg:check alex-kassel/stable-fingerprint --json

Changelog

Please see CHANGELOG.md for more information on what has changed recently.

Security Vulnerabilities

Please review the security policy to report vulnerabilities.

License

The MIT License (MIT). Please see License File for more information.

alex-kassel / stable-fingerprint

Maintainers

Package info

Statistics

Security