A php fingerprint library has three jobs that fail in different ways: collect signals without trusting the client, survive a proxy chain, and answer one question about a match. globus-studio/fingerprint does all three on PHP 8.3 and newer, and it names what it cannot do.
Code: Fingerprint-PHP, MIT licensed.
One call, one object
$config = FingerprintConfig::balanced(secret: $_ENV['APP_FINGERPRINT_SECRET']);
$result = FingerprintBuilder::fromGlobals($config)->build();
echo $result->id();
echo $result->confidence();
fromGlobals() reads the request, build() returns an immutable result with an identifier and a confidence score. diagnostics() exposes the per-signal detail, which is what an incident review actually reads.
Proxies are an explicit decision
$config = FingerprintConfig::balanced($secret)
->withTrustedProxies(['10.0.0.0/8', '172.16.0.0/12'])
->withTrustedHeaders(['x-forwarded-for', 'x-forwarded-proto']);
Forwarded headers are ignored unless REMOTE_ADDR is in the trusted list. The rule is short and it stops the most common attack: a client that sets its own X-Forwarded-For and picks which fingerprint it wants.
On a migration this is the first setting to test. A wrong list collapses every visitor into one identifier, and the symptom looks like traffic from a single machine.
Configuration without surprises
FingerprintConfig has named constructors (balanced(), and the other profiles) rather than a bare array, and each with*() method returns a new object. A configuration passed into a factory cannot be mutated by the next call, which is the bug that appears when a long-running worker chooses a profile for one request and keeps it for the next thousand.
The secret comes from the environment and is not read from a constant. Without it, the identifier is derived from data the client controls entirely, and the whole exercise becomes a random number with extra steps.
Matching returns a level
compare() takes two results and returns a match with a level. level()->isSuspicious() is the branch a login form needs: ask for the second factor, or let the session continue.
A boolean would force a threshold into the library, and the right threshold depends on the product. A level leaves the decision where the risk is understood.
Profiles are the privacy surface
strict keeps minimal signals and no raw values. balanced is the default for security work. maximum adds high-signal collectors and expects a documented legal basis. custom lets the application define its own set.
The configuration object makes the choice visible in the codebase, which is what a privacy review asks for. A hardcoded maximum buried in a service provider is the same behaviour with no record of the decision.
Diagnostics without a logger
The builder accepts an optional PSR-compatible logger. Without it, the result still carries diagnostics, so a debugging session does not require wiring a logging stack first.
That is a small design detail with a practical effect: an artisan-style script can print why two fingerprints differ without touching the application’s logging configuration.
Documentation is part of the package
Privacy, configuration, signals, trusted proxies, limitations, algorithm versioning, testing and an implementation checklist, plus framework notes for Laminas and Slim.
Algorithm versioning deserves a mention. When the signal set changes between versions, stored fingerprints stop matching, and a document that names the version is what lets a team plan the migration instead of discovering it in the logs.
What it cannot do
It cannot identify a device with certainty. NAT, VPN, mobile networks, privacy settings and browser updates move the signals, and the readme says a fingerprint must not be the only factor for authentication or blocking.
Related: qr code renderer for another PHP library with a small surface, and modular php framework for the application that usually calls this one.