Easily use Hashids with Laravel models.

In some cases I really like to use Hashids instead of uuids as my model keys. For me Hashids are less awkward to read and the resulting URL looks a bit nicer in my opinion. This package is inspired by laravel-model-uuid by Michael Dyrynda and aims to make it a breeze to start using Hashids as your model keys.

Installation

You can install the package via composer:

composer require antoninmasek/laravel-model-hashids

You can publish the config file with:

php artisan vendor:publish --tag="laravel-model-hashids-config"

This is the contents of the published config file:

return [
    /*
     * The following column will be filled with the generated hash id. If you decide to also bind
     * models to hash_id, then this column will be used as route key name.
     */
    'hash_id_column' => 'hash_id',

    /*
     * Define the column name, which will be used to generate the hash id. This column has to contain
     * a numeric value or an array of numbers and should be unique for each model to prevent
     * potential collisions.
     */
    'model_key' => 'id',
];

This package uses antoninmasek/laravel-hashids in the background. And if you wish to configure some aspects of the underlying hash id generation, then please take a look at a readme of the package.

Usage

To use this package you'll be most interested in the following two traits: GeneratesHashId and BindsOnHashId.

Generating hash id

In order for your model to automatically get a hash id after it is created just use GeneratesHashId trait on your model:

use AntoninMasek\Hashids\Traits\GeneratesHashId;

class YourModel extend Model
{
    use GeneratesHashId;
}

Binding on hash id

To also bind your model to hash id you also need to use BindsOnHashId trait:

use AntoninMasek\Hashids\Traits\GeneratesHashId;
use AntoninMasek\Hashids\Traits\BindsOnHashId;

class YourModel extend Model
{
    use GeneratesHashId;
    use BindsOnHashId;
}

Configuration

If you need to execute some logic in order to determine salt/alphabet/minlength you have a few callbacks at your disposal:

Global

If you want to set these globally you may use the following callbacks. The callback is supplied with the model as a parameter.

use AntoninMasek\Hashids\ModelHashids;

ModelHashids::generateSaltUsing(function(Model $model) {
    // your logic   
    return $salt;
});

ModelHashids::generateMinLengthUsing(function(Model $model) {
    // your logic   
    return $minLength;
});

ModelHashids::generateAlphabetUsing(function(Model $model) {
    // your logic   
    return $alphabet;
});

Local

If you wish to have a specific logic just for a certain model you may define these methods on the desired model:

// Overwrite the column to fill with hash id for this specific model
public function hashIdColumn(): string;

// Overwrite the column to use for hash id generation for this specific model
public function hashIdKeyColumn(): string;

// Overwrite the logic to generate salt for this specific model
public function hashIdSalt(): string;

// Overwrite the logic to generate alphabet for this specific model
public function hashIdAlphabet(): string;

// Overwrite the logic to generate min length for this specific model
public function hashIdMinLength(): string;

Precedence

This is the order in which the values are taken:

1. Model specific logic
2. Global logic
3. Config values
4. Hashids package

Regenerating hash id

If you wish to regenerate a hash id for a particular model with current configuration you may do so as follows:

// This will save the new hash id directly to database
$model->regenerateHashId();

// This will just regenerate the hash id on the instance without persisting it.
// You will need to call the save() method to persist it.
$model->regenerateHashId(saveToDatabase: false);

Limitations

If your model key is auto-incrementing then, at least at the moment, there are 2 round-trips to the database. 1st to create the model and receive the ID and then 2nd to set the hash_id based on the ID.

Note: Updating eloquent event is not fired, when setting the hash_id. This is the default behaviour since version 0.6.0. It is still possible to change this via save_quietly config setting.

Testing

composer test

Changelog

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

Credits

Antonín Mašek

License

The MIT License (MIT). Please see License File for more information.

Special thanks

• To Michael Dyrynda for his laravel-model-uuid package, by which this package is heavily inspired.
• To Spatie for their amazing skeleton which I used to scaffold this repository.