README

Add Stripe-like universal ids to your models that can be decoded back to their integer ids.

Installation

Caution

Please note that this is a new package and, even though it is well tested, it should be considered pre-release software

You can install the package via composer:

composer require shabushabu/laravel-uid

Publish the config file with:

php artisan vendor:publish --tag="uid-config"

Prefixes

You will then have to add all your models to the prefixes array in the config file:

return [
    'prefixes' => [
        'usr' => \App\Models\User::class,
    ],
];

Create a custom alphabet

Run the following command and add the output to your .env file:

php artisan uid:alphabet

Usage

The first step for every model should be to add the provided HasUid trait. This ensures that route model binding works as expected with UIDs.

use ShabuShabu\Uid\Concerns\HasUid;

class User extends Model
{
    use HasUid;
}

Encode from an id

use ShabuShabu\Uid\Service\Uid;

$uid = Uid::make()->encodeFromId(User::class, 1);

// something like: usr_86Rf07xd4z

Encode a model

use ShabuShabu\Uid\Service\Uid;

$uid = Uid::make()->encode(User::find(1));

// something like: usr_86Rf07xd4z

Decode a uid

use ShabuShabu\Uid\Service\Uid;

$decoded = Uid::make()->decode('usr_86Rf07xd4z');

// returns an instance of DecodedUid::class

Decode to a model

use ShabuShabu\Uid\Service\Uid;

$model = Uid::make()->decodeToModel('usr_86Rf07xd4z');

// returns an instance of User::class

$model = Uid::make()->withTrashed()->decodeToModel('usr_86Rf07xd4z');

// returns an instance of User::class, even if the model is trashed

Check if a uid is valid

use ShabuShabu\Uid\Service\Uid;

$valid = Uid::make()->isValid('usr_86Rf07xd4z');

// returns true if the prefix exists

$valid = Uid::make()->isValid('usr_86Rf07xd4z', User::class);

// returns true if the prefix exists and belongs to the class

Retrieve the alias of a given class

use ShabuShabu\Uid\Service\Uid;

$alias = Uid::alias(User::class);

// returns usr

Model info based on a UID

If you have a UID and would like some info about it, then you can use the following command:

php artisan uid:info

Bonus idea

Use the prefixes as your morph map:

use Illuminate\Database\Eloquent\Relations\Relation;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Relation::enforceMorphMap(config('uid.prefixes'));
    }
}

A word of warning

Please note that this package does not work with string or compound primary keys. The underlying Squids library supports the encoding of an integer array, so compound primary keys might eventually be supported.

Testing

composer test

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

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

shabushabu / laravel-uid

Maintainers

Details