tobymaxham / laravel-hashid
Hashed IDs for Laravel: hide your database IDs in URLs, route model binding, queries, validation and JSON.
Requires
- php: ^8.3
- hashids/hashids: ^5.0
- illuminate/database: ^12.0|^13.0
- illuminate/support: ^12.0|^13.0
Requires (Dev)
- larastan/larastan: ^3.0
- laravel/pint: ^1.21
- orchestra/testbench: ^10.0|^11.0
- pestphp/pest: ^4.0
Suggests
- ext-bcmath: Alternative to GMP. At least one is required.
- ext-gmp: Recommended for best performance with hashids/hashids.
Provides
None
Conflicts
None
Replaces
None
README
This Laravel package ensures that IDs are not directly visible in URLs or other public areas.
Instead, they are encoded and, for example, products/34 is converted to products/h:J7dVgYxKPwyQejOMnL.
Requirements
- PHP 8.3 or higher
- Laravel 12 or 13
- PHP extension GMP or BCMath (GMP is faster)
Use version 1.x for older PHP or Laravel versions.
Upgrading from 1.x? Version 2.0 changes all hashes by default. Please read the upgrade guide first, or let your AI agent do the upgrade.
Installation
You can install the package via composer:
composer require tobymaxham/laravel-hashid
This package relies on
hashids/hashids, which requires either the GMP or BCMath extension. GMP is recommended for best performance and should be installed if possible.
Configuration
Publish the configuration file with:
php artisan vendor:publish --tag=hashid-config
The configuration file config/hashids.php looks like this (every option is explained in the file):
return [ 'prefix' => env('HASH_PREFIX', 'h:'), 'prefix_mode' => env('HASH_PREFIX_MODE', 'strict'), 'salt' => env('HASH_SALT', 'your-salt-string'), 'previous_salts' => env('HASH_PREVIOUS_SALTS', ''), 'per_model' => env('HASH_PER_MODEL', true), 'accept_legacy_hashes' => env('HASH_ACCEPT_LEGACY', false), 'length' => env('HASH_LENGTH', 18), 'alphabet' => env('HASH_ALPHABET', 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890'), 'exception' => \TobyMaxham\HashId\Exceptions\InvalidHashIdException::class, 'exception_message' => 'The given hash id is invalid.', 'disable_exception' => false, ];
Prefix
Every hash starts with the prefix (default h:), e.g. h:J7dVgYxKPwyQejOMnL.
No prefix: set an empty value. This is fully supported, in routes and everywhere else.
HASH_PREFIX=
Prefix mode: HASH_PREFIX_MODE controls which hashes are accepted when decoding.
| Mode | Accepts | Use case |
|---|---|---|
strict (default) |
only h:J7dVgYxKPwyQejOMnL |
one format everywhere |
optional |
h:J7dVgYxKPwyQejOMnL and J7dVgYxKPwyQejOMnL |
prefix in public URLs, plain hash in APIs (safeHashID()) |
Hashes are always generated with the prefix. safeHashID() returns the hash without the prefix.
Allowed characters: letters (a-z, A-Z), digits and - . _ ~ :. These work in URLs without encoding.
Any other character (e.g. /, ?, +, &, spaces or umlauts) throws an InvalidArgumentException. This also applies to prefixes per model.
The
:in the default prefix is fine in URL paths. If a proxy or CDN encodes it, use a prefix likeh_orh-.
Usage
Using the Facade
These methods use the global salt. For the hashes of a model use IdHasher::for(Product::class) (see Hashes per model).
use \TobyMaxham\HashId\Facades\IdHasher; $hash = IdHasher::encodeId(34); // result: h:J7dVgYxKPwyQejOMnL $id = IdHasher::decodeId($hash); // result: 34 IdHasher::encodeIdWithoutPrefix(34); // result: J7dVgYxKPwyQejOMnL IdHasher::decodeId('h:invalid', false); // result: null (no exception)
Using Dependency Injection
If you prefer to use dependency injection:
use TobyMaxham\HashId\IdHasherManager; public function show(IdHasherManager $idHasher, string $hash) { $id = $idHasher->for(Product::class)->decodeId($hash); return Product::findOrFail($id); }
For models with the Hasher trait, Product::findByHashIdOrFail($hash) is shorter (see Queries).
Automatically Decode Hash IDs
You can use the trait Hasher in your models to automatically decode hash IDs:
use TobyMaxham\HashId\Hasher; use TobyMaxham\HashId\Interfaces\HasHashId; class Product extends Model implements HasHashId { use Hasher; }
Now you can use them in routes:
// web.php Route::get('products/{product}', [ProductController::class, 'show']); // ProductController.php class ProductController extends Controller { public function show(Product $product) { return $product; } }
Implementing HasHashId is optional, but lets other code (e.g. API resources) detect hashed models. It extends the older Hashing interface.
You can also extend TobyMaxham\HashId\ModelWithHasher instead.
Invalid hashes return a 404. Custom fields like {product:slug}, scoped bindings like products/{product}/reviews/{review} and ->withTrashed() routes are supported.
The model also gets these methods:
$product->hashID(); // h:J7dVgYxKPwyQejOMnL $product->safeHashID(); // J7dVgYxKPwyQejOMnL
Hashing only works for integer keys. Do not combine
HasherwithHasUuidsorHasUlids.
Hashes per model
Every model gets its own hashes, so user 400 and post 400 have different hashes.
A hash of one model can not be used for another model (the route returns a 404).
The model key is added to the salt. By default it is the table name. Set your own key, so the hashes stay the same when you rename the table:
class User extends Model { use Hasher; // any of these: public const HASH_ID_KEY = 'user'; protected string $hashIdKey = 'user'; public function hashIdKey(): string { return 'user'; } }
Changing the key changes all hashes of the model.
Prefix per model: works the same way with HASH_ID_PREFIX, $hashIdPrefix or hashIdPrefix().
null uses the global prefix, '' disables the prefix for this model.
class User extends Model { use Hasher; public const HASH_ID_PREFIX = 'usr_'; // usr_J7dVgYxKPwyQejOMnL }
Outside of models, get the hasher of a model with IdHasher::for():
IdHasher::for(User::class)->encodeId(400); IdHasher::for($user)->decodeId($hash); IdHasher::for('users')->encodeId(400); // custom key
IdHasher::encodeId() without for() uses the global salt.
To use the same hashes for all models (like 1.x), disable it:
HASH_PER_MODEL=false
Queries
Find models by hash:
Product::findByHashId($hash); // ?Product Product::findByHashIdOrFail($hash); // Product or ModelNotFoundException (404) Product::findManyByHashIds([$hash1, $hash2]); // Collection, invalid hashes are skipped Product::findByHashId($hash, ['id', 'name']); // only these columns Product::decodeHashId($hash); // ?int, no query Product::decodeHashIds([$hash1, $hash2]); // list of ints, invalid hashes are skipped
Or use the scopes in any query, on relations and inside whereHas():
Product::whereHashId($hash)->first(); Product::whereHashId($hash1)->orWhereHashId($hash2)->get(); Product::whereHashIdIn([$hash1, $hash2])->get(); Product::whereHashIdNot($hash)->get(); Product::whereHashIdNotIn([$hash1, $hash2])->get(); $product->reviews()->whereHashId($reviewHash)->first(); Review::whereHas('product', fn ($query) => $query->whereHashId($productHash))->get();
- The query is a normal
where id = ?/where id in (...)on the qualified key (products.id), so joins work. - Invalid hashes or hashes of another model never throw:
whereHashId()matches no rows,findByHashId()returnsnullwithout a query. Model::find()andwhere('id', ...)are not changed and still expect the real id.
Validation
use TobyMaxham\HashId\Rules\HashId; use TobyMaxham\HashId\Rules\HashIdExists; $request->validate([ 'product_id' => ['required', new HashIdExists(Product::class)], // valid hash and record exists 'category_id' => ['nullable', new HashId(Category::class)], // valid hash, no query 'active_id' => [(new HashIdExists(Product::class))->where(fn ($query) => $query->where('active', true))], ]);
Both rules use Laravel's validation.exists message ("The selected :attribute is invalid.").
Request
Get the id from a hash in the request (null for missing or invalid values):
$id = $request->hashId('product_id', Product::class); // ?int $ids = $request->hashIds('product_ids', Product::class); // list<int>, invalid hashes are skipped
JSON / toArray()
By default toArray() and JSON contain the real id. Add SerializesHashIds to output hashes instead:
use TobyMaxham\HashId\Hasher; use TobyMaxham\HashId\SerializesHashIds; class Review extends Model { use Hasher; use SerializesHashIds; // optional: foreign keys to hash with the salt of their model protected array $hashIdForeignKeys = ['product_id' => Product::class]; } $review->toArray(); // ['id' => 'h:…', 'product_id' => 'h:…', ...] $review->id; // still the real id, relations keep working
Artisan
php artisan hashid:encode 34 400 --model="App\Models\Product"
php artisan hashid:decode h:J7dVgYxKPwyQejOMnL --model=products
Without --model the global salt is used.
Exceptions
IdHasher::decodeId() throws InvalidHashIdException for invalid hashes (configurable with exception and exception_message, or disabled with disable_exception).
Pass false as second argument to get null instead: IdHasher::decodeId($hash, false).
Security
-
Set your own salt with
HASH_SALTand keep it secret. With the default salt (your-salt-string) anyone can decode your hashes. In production the package logs a warning once per process, andphp artisan aboutshows the salt status. -
Hashes are not encryption. They only hide the real ids and prevent counting through them (
/users/1,/users/2, …). They are no replacement for authorization: always check access with policies or gates. -
Rotate a leaked salt without breaking old links: set the new salt and add the old one to
HASH_PREVIOUS_SALTS. Old hashes are still accepted, new hashes are created with the new salt.HASH_SALT=new-secret HASH_PREVIOUS_SALTS=old-secret
-
The config is checked when the first hash is created: an invalid
alphabet,length,exceptionor a prefix with characters that are not URL safe throw anInvalidArgumentExceptionwith the config key in the message. -
Laravel Octane: supported. The hasher only keeps data from the config, no request state.
Testing
composer test
composer test-coverage
composer analyse
Changelog
Please see CHANGELOG for more information on what has changed recently.
Security Vulnerabilities
If you've found a bug regarding security please mail git@maxham.net instead of using the issue tracker.
Support me
Credits
License
The MIT License (MIT). Please see License File for more information.