README

A Laravel package for encoding and decoding database IDs using Sqids (next-generation Hashids). This package provides a clean way to obfuscate your database IDs in URLs and API responses while maintaining Laravel conventions.

Features

🔢 Encode/decode database IDs using Sqids (next-gen Hashids)
🛡️ Built-in profanity filter with customizable blocklist
🎭 Eloquent model trait for automatic ID handling
🛣️ Route model binding support with encoded IDs
✍️ Signed IDs with expiration support
🔧 Helper functions for easy usage
⚙️ Configurable alphabet, length, and blocklist
🚀 Laravel 10, 11, and 12 support
🧪 Comprehensive test suite with Pest
📝 Full static analysis with PHPStan
⚡ Better performance than traditional Hashids

Requirements

PHP 8.2+
Laravel 10.x, 11.x, or 12.x
BCMath or GMP extension (automatically handled by Sqids)

Installation

Install the package via Composer:

composer require litepie/hashids

The service provider will be automatically registered. To publish the config file:

php artisan vendor:publish --provider="Litepie\Hashids\HashidsServiceProvider" --tag="hashids-config"

Configuration

The configuration file config/hashids.php allows you to customize:

return [
    'alphabet' => env('HASHIDS_ALPHABET', 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'),
    'length' => env('HASHIDS_LENGTH', 0),
    'blocklist' => env('HASHIDS_BLOCKLIST') ? explode(',', env('HASHIDS_BLOCKLIST')) : null,
];

You can also set these values in your .env file:

HASHIDS_ALPHABET=abcdefghijklmnopqrstuvwxyz1234567890
HASHIDS_LENGTH=10
HASHIDS_BLOCKLIST=word1,word2,word3

Usage

Helper Functions

// Encode an ID
$hash = hashids_encode(123); // returns something like "bM"

// Decode a hash
$id = hashids_decode('bM'); // returns 123

// Encode multiple values
$hash = hashids_encode([123, 456]); // encode multiple values

// Decode to array
$ids = hashids_decode('86Rf07'); // returns [123, 456]

// Using new Sqids functions (aliases)
$hash = sqids_encode(123); // same as hashids_encode
$id = sqids_decode('bM'); // same as hashids_decode

Facade

use Litepie\Hashids\Facades\Hashids;

$hash = Hashids::encode([123]);
$id = Hashids::decode('bM');

Eloquent Model Trait

Add the trait to your Eloquent models:

use Litepie\Hashids\Traits\Hashids;

class User extends Model
{
    use Hashids;
    
    // Your model code...
}

Available Methods

// Get encoded ID
$user = User::find(1);
echo $user->eid; // encoded ID attribute
echo $user->getRouteKey(); // for route model binding

// Find by encoded ID
$user = User::findOrFail('bM');
$user = User::findOrNew('bM');

// Signed IDs (with expiration)
$signedId = $user->getSignedId('+1 hour'); // expires in 1 hour
$signedId = $user->getSignedId(1234567890); // expires at timestamp
$signedId = $user->getSignedId(); // never expires

// Find by signed ID
$user = User::findBySignedId($signedId);

Route Model Binding

The trait automatically supports Laravel's route model binding:

// routes/web.php
Route::get('/users/{user}', function (User $user) {
    return $user;
});

Now you can use encoded IDs in your URLs:

/users/bM instead of /users/1

Security

The alphabet is automatically shuffled for uniqueness
Built-in profanity filter prevents offensive words in IDs
Signed IDs include salt verification and optional expiration
IDs are obfuscated but not encrypted (don't rely on them for security)
Customizable blocklist for additional word filtering

Why Sqids over Hashids?

This package uses Sqids instead of traditional Hashids, providing:

⚡ Better Performance - More efficient algorithm
🛡️ Built-in Profanity Filter - Automatic offensive word prevention
🎛️ Custom Blocklist - Block specific words from appearing in IDs
🔧 Modern PHP - Optimized for PHP 8.2+
📈 Active Development - Regular updates and improvements

Testing

composer test

Running Static Analysis

composer analyse

Code Style Fixing

composer format

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

This package is open-sourced software licensed under the MIT license.

Support

Issues: GitHub Issues
Documentation: README
Source: GitHub Repository

Acknowledgments

Built on top of sqids/sqids (next-generation Hashids)
Maintains backward compatibility with Hashids API
Inspired by the original Litepie framework implementation

litepie / hashids

Maintainers

Details