laragear/fingerprint

Ridiculously fast non-cryptographic hashes in your application or Eloquent Models

v3.0.0 2026-03-30 03:31 UTC

Requires

• php: ^8.3

Requires (Dev)

• laragear/meta-testing: ^4.2
• orchestra/testbench: 10.*|11.*

Suggests

• illuminate/database: To use the [AsFingerprint] cast (^11.0|^12.0).

MIT

• Italo Baeza C.

README

Ridiculously fast non-cryptographic hashes in your application or Eloquent Models.

use Laragear\Fingerprint\Fingerprinter;

$fingerprint = Fingerprinter::of('some-string-or-object');

return $fingerprint->hash();

Become a sponsor

Your support allows me to keep this package free, up-to-date and maintainable.

Requirements

• PHP 8.3 or later
• Laravel 12 or later

Installation

You can install the package via Composer.

composer require laragear/fingerprint

How does this work?

This adds the Fingerprint service in your service container to conveniently create non-cryptographic fingerprint hashes of strings, Stringable instance, resources, or any object in a memory-efficient way.

It leverages the power of hash_init() and json_encode to hash anything, including Eloquent Models or Collections, and uses the fastest hash algorithm around, xxHash by default.

Usage

To create fingerprints, you may use the Fingerprint facade, and any of its methods to create a hash.

use Laragear\Fingerprint\Facades\Fingerprint;

// Make a Base64 encoded hash
Fingerprint::make($hashable);
Fingerprint::base64($hashable);

// Make a Base64 URL-safe hash to transmit over the network.
Fingerprint::base64Url($hashable);

// Make a "raw" binary hash.
Fingerprint::binary($hashable);

// Make a hexadecimal hash.
Fingerprint::hex($hashable);

// Compare two hashes.
Fingerprint::is($expected, $string);
Fingerprint::isNot($expected, $string);

Algorithms

By default, Fingerprints are hashed using the xxh3 algorithm, available since PHP 8.1, which is the fastest non-cryptographic algorithm around and returns short hashes.

You may change it using the second parameter when creating fingerprints, and custom options as third parameter to be passed to hash()|hash_init().

use Laragear\Fingerprint\Facades\Fingerprint;

$hash = Fingerprint::base64($value, 'xxh128', [
    'seed' => 33
]);

Note

The algorithms available will depend on your environment. You may check them using hash_algos().

Changing the default algorithm

You may change the default format using the Laragear\Fingerprint\Fingerprinter::$algorithm with the one you want to be passed down to hash()|hash_init() methods. You may do this while your application boots in your App\Providers\AppServiceProvider or bootstrap\app.php.

use Illuminate\Foundation\Application;
use Laragear\Fingerprint\Fingerprinter;

return Application::configure(basePath: dirname(__DIR__))
    ->booted(function () {
        Fingerprinter::$algorithm = 'sha256';
    })
    ->create();

Eloquent Models

You can use the Laragear\Fingerprint\HasFingerprints trait in your models to automatically calculate fingerprints in your model when saving them into the database.

Set the trait and use the updateFingerprints() method to return an array of all the fingerprints to calculate before persistence.

use Illuminate\Database\Eloquent\Model;
use Laragear\Fingerprint\HasFingerprints;
use Laragear\Fingerprint\Fingerprinter;

/**
 * @property string $body 
 */
class Article extends Model
{
    use HasFingerprints;
    
    /**
     * Receive a Fingerprinter instance and returns an array of attributes with the fingerprints.
     *
     * @return array<string, string>
     */
    public function updateFingerprints(Fingerprinter $fingerprinter): array
    {
        return [
            'fingerprint' => $fingerprinter->make($this->body)
        ];
    }
}

Since you receive a Fingerprinter instance, you can create a fingerprint anyway you want.

use Laragear\Fingerprint\Fingerprinter;

public function updateFingerprints(Fingerprinter $fingerprinter): array
{
    return [
        'fingerprint' => $fingerprinter->base64Url($this->body)
    ];
}

If you want to programmatically disable (or enable) the fingerprint update, use the shouldUpdateFingerprints() method.

/**
 * Checks if the model should update its fingerprints before persisting into storage.
 */
public function shouldUpdateFingerprints(): bool
{
    return $this->isPublished();
}

Laravel Octane compatibility

• There are no singletons using a stale app instance.
• There are no singletons using a stale config instance.
• There are no singletons using a stale request instance.
• There are no static properties written during a request.

There should be no problems using this package with Laravel Octane.

Security

If you discover any security-related issues, issue a Security Advisor

License

This specific package version is licensed under the terms of the MIT License, at the time of publishing.

Laravel is a Trademark of Taylor Otwell. Copyright © 2011–2026 Laravel LLC.