Fingerprint: Same data, same fingerprint
hash(json_encode($data)) changes when keys move and blurs 1 with 1.0. Fingerprint gives PHP data a stable SHA-256 or HMAC fingerprint, whatever the key order, machine or locale, with rules for what to ignore or normalize. It also builds the exact ordered signatures that payment gateways and webhooks expect.
Everything you need to compare and sign PHP data
One call for the default, a fluent builder when you need rules.
Key Order Never Matters
Maps are ordered canonically at every level, while lists keep their order unless you call unordered().
Types Preserved
1, '1', 1.0 and true differ, and null is not a missing key, unless you normalize them.
Path Rules
ignore('items.*.cached_at'), only(), at('email')->trim()->lower(), precision(2), sortBy('id').
Hashing and HMAC
SHA-256 by default, any hash() algorithm, hmac($secret), namespaces, and hex, binary or base64 output.
Ordered Signatures
Fingerprint::signature($payload)->fields([...]) rebuilds a gateway's exact message and verifies it in constant time.
Explainable
result()->canonical() shows the exact bytes behind a fingerprint, so a difference is never a mystery.
A quick look
Three methods cover most uses; rules are there when you need them.
1use Pharaonic\Fingerprint\Fingerprint; 2 3// The same data gives the same fingerprint, whatever the key order. 4$fingerprint = Fingerprint::make($product); 5 6// Later: has anything changed? 7Fingerprint::verify($product, $fingerprint); // true 8 9// Leave out fields that change on every save.10Fingerprint::for($product)->ignore('updated_at')->make();Fingerprint Questions
Quick answers about installing and using Fingerprint.
What is Fingerprint?
Deterministic fingerprints of PHP data, whatever the key order, plus ordered HMAC signatures for payment gateways and webhooks. It's a free, open-source PHP package by Pharaonic.
How do I install Fingerprint?
Run composer require pharaonic/php-fingerprint in your project's root directory.
What does Fingerprint require?
The latest release requires PHP 8.0+.
Why not hash(json_encode($data))?
json_encode() keeps key order, so the same data with keys in another order gives another hash. It also writes 1.0 as 1 and depends on ini settings for floats. Fingerprint orders maps canonically, keeps types apart, and encodes floats from their exact bits.
What is the difference between a fingerprint and a signature?
A fingerprint answers "is this the same data?": key order never matters and you choose what to ignore. A signature answers "does this payload carry the signature a protocol defines?": fields are joined in exactly the declared order, as payment gateways and webhooks require. The two never share a format.
How do I verify a Paymob callback?
List Paymob's fields in their documented order with Fingerprint::signature($transaction)->fields([...]), choose algorithm('sha512') and hmac($secret), then call verify() with the hmac Paymob sent. The documentation has a complete step-by-step example for plain PHP and Laravel.
Will fingerprints match across servers and PHP versions?
Yes. The canonical form never depends on the locale, ini settings or the PHP version, and hand-written golden vectors check it on every supported PHP line. Only rules that rely on Unicode tables or timezone databases can differ between builds, and the documentation lists them.
Does it depend on Laravel or another framework?
No. Fingerprint is plain PHP with no runtime dependency besides ext-mbstring.
Is Fingerprint free to use?
Yes. Fingerprint is open source under the MIT license, so you can use it in personal and commercial projects.
Where can I find the Fingerprint documentation?
Read the Fingerprint documentation for setup, rules, signatures and usage examples.
How do I report a bug or contribute to Fingerprint?
Open an issue or a pull request on GitHub, or ask in the Pharaonic Discord.
Ready to dig in?
Read the full documentation for canonical rules, paths and wildcards, filters, string, number and date normalization, list ordering, objects, hashing and HMAC, ordered signatures, files and streams, and debugging.