Laravel Hashids
This package provides a trait that will generate hashids when saving any Eloquent model.
Hashids
Hashids is a small package to generate YouTube-like IDs from numbers. It converts numbers like 347 into strings like yr8.
Installation
You can install the package via composer:
composer require bvtterfly/laravel-hashids
You can publish the config file with:
php artisan vendor:publish --tag="hashids-config"
This is the contents of the published config file:
return [
/*
|--------------------------------------------------------------------------
| Default Salt
|--------------------------------------------------------------------------
|
| This is the salt that uses by Hashids package to generate unique id.
|
*/
'salt' => config('app.name')
];
Usage
Your Eloquent models should have the Bvtterfly\LaravelHashids\HasHashId trait that contains an abstract getHashIdOptions method that you must implement yourself, and it should return the Bvtterfly\LaravelHashids\HashIdOptions class.
Your models' migrations should have a field to save the generated hashid to.
Here's an example of what a model would look like:
namespace App\Models;
use Bvtterfly\LaravelHashids\HasHashId;
use Bvtterfly\LaravelHashids\HashIdOptions;
use Illuminate\Database\Eloquent\Model;
class Post extends Model
{
use HasHashId;
public function getHashIdOptions(): HashIdOptions
{
return HashIdOptions::create()->saveHashIdTo('hashid');
}
}
By default, Package will generate hashids from models'
id.
And Its migration:
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
return new class extends Migration
{
public function up()
{
Schema::create('posts', function (Blueprint $table) {
$table->increments('id');
$table->string('hashid')->nullable(); // Field name same as your `saveHashIdTo`
//...
$table->timestamps();
});
}
}
The
hashidcolumn is generated from theidfield, Butidis an auto-increment column and doesn't have value before saving in the DB. So, Thehashidcolumn must be nullable. And The Package will generatehashidand update the model after being saved in the database.
Generate from Hex numbers
If you want to generate hashids from hex numbers like Mongo's ObjectIds, you can change the type to the hex:
public function getHashIdOptions(): HashIdOptions
{
return HashIdOptions::create()
->saveHashIdTo('hashid')
->setType('hex') // default = int
;
}
Generate from another field
public function getHashIdOptions(): HashIdOptions
{
return HashIdOptions::create()
->saveHashIdTo('hashid')
->generateHashIdFrom('custom_key')
;
}
Generate from field with value
By default, This package will generate hashids and update the model from the auto-incremented id column after being saved in the database. Still, if your field has value, you can change it to generate hashids while saving:
public function getHashIdOptions(): HashIdOptions
{
return HashIdOptions::create()
->saveHashIdTo('hashid')
->setAutoGeneratedField(false)
;
}
Use the same hashids among models
The package will add the models' class to the default salt to generate a unique output id per model. If you want your Post and User models to share the same output id when id = 1:
public function getHashIdOptions(): HashIdOptions
{
return HashIdOptions::create()
->saveHashIdTo('hashid')
->setGenerateUniqueHashIds(false)
;
}
Use padding to make your output ids longer
Without padding, encoding of 1 returns something like jR, but You can use padding to have a longer output id.
Note that output ids are only padded to fit at least a certain length. It doesn't mean that they will be exactly that length.
public function getHashIdOptions(): HashIdOptions
{
return HashIdOptions::create()
->saveHashIdTo('hashid')
->setMinimumHashLength(10)
;
}
Using a custom alphabet
public function getHashIdOptions(): HashIdOptions
{
return HashIdOptions::create()
->saveHashIdTo('hashid')
// use all lowercase alphabet instead of 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890'
->setAlphabet('abcdefghijklmnopqrstuvwxyz')
;
}
Using Hashids in routes
To use the hashids in routes, you may specify the hashid column in the route parameter definition:
use App\Models\Post;
Route::get('/posts/{post:hashid}', function (Post $post) {
return $post;
});
or If you would like model binding to always use the hashid column other than id when retrieving a given model class, you may override the getRouteKeyName method on the Eloquent model:
/**
* Get the route key for the model.
*
* @return string
*/
public function getRouteKeyName()
{
return 'hashid';
}
Testing
composer test
Changelog
Please see CHANGELOG for more information on what has changed recently.
Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities.
Credits
License
The MIT License (MIT). Please see License File for more information.
720 Jan 3, 2023
139 Dec 25, 2022
996 Dec 28, 2022
33 Nov 6, 2022
139 Dec 27, 2022
690 Nov 27, 2022
40 Jun 5, 2022
845 Jan 1, 2023
3 Feb 10, 2022
296 Dec 24, 2022
2 Oct 14, 2021
1.5k Jan 7, 2023
3.6k Dec 30, 2022
955 Dec 25, 2022
67 Dec 7, 2022
25 Dec 14, 2022