README

Laravel Sqids (pronounced "squids") allows you to easily generate Stripe/YouTube looking IDs for your Laravel models. These IDs are short and are guaranteed to be Collision free.

For more information on Sqids, we recommend checking out the official Sqids (formerly Hashids) website: https://sqids.org.

Installation

You can install the package via composer:

composer require red-explosion/laravel-sqids

You can publish the config file with:

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

Usage

Using Sqids

To use Laravel Sqids, simply add the RedExplosion\Sqids\Concerns\HasSqids trait to your model:

use RedExplosion\Sqids\Concerns\HasSqids;

class User extends Authenticatable
{
    use HasSqids;
}

You will now be able to access the Sqid for the model, by calling the sqid attribute:

$user = User::first();

$sqid = $user->sqid; // usr_A3EyoEb2TO

The result of $sqid will be encoded value of the models primary key along with the model prefix.

Tip

Only integers can be encoded, and therefore we recommend using this package in conjunction with auto incrementing IDs.

If you would like to set a custom prefix for the model, you can override it by setting a $sqidPrefix property value on your model like so:

use RedExplosion\Sqids\Concerns\HasSqids;

class User extends Authenticatable
{
    use HasSqids;
    
    protected string $sqidPrefix = 'user';
}

$user = User::first();
$sqid = $user->sqid; // user_A3EyoEb2TO

Builder Mixins

Laravel Sqids provides a number of Eloquent builder mixins to make working with Sqids seamless.

Find by Sqid

To find a model by a given Sqid, you can use the findBySqid method:

$user = User::findBySqid('usr_A3EyoEb2TO');

If the model doesn't exist, null will be returned. However, if you would like to throw an exception, you can use the findBySqidOrFail method instead which will throw a ModelNotFoundException when a model can't be found:

$user = User::findBySqidOrFail('usr_invalid');

Where Sqid

To add a where clause to your query, you can use the whereSqid method:

$users = User::query()
    ->whereSqid('usr_A3EyoEb2TO')
    ->get();

This will retrieve all users where the Sqid/primary key matches the given value.

Where Sqid in

To get all models where the Sqid is in a given array, you can use the whereSqidIn method:

$users = User::query()
    ->whereSqidIn('id', ['usr_A3EyoEb2TO'])
    ->get();

This will return all users where the id is in the array of decoded Sqids.

Where Sqid not in

To get all models where the Sqid is not in a given array, you can use the whereSqidNotIn method:

$users = User::query()
    ->whereSqidNotIn('id', ['usr_A3EyoEb2TO'])
    ->get();

This will return all users where the id is not in the array of decoded Sqids.

Validation Rule

There may be times where you need to validate a sqid in a form request. Laravel Sqids provides a SqidsExists rule to handle this automatically.

use RedExplosion\Sqids\Rules\SqidExists;

$validated = validator(
    ['customer_id' => 'cus_A3EyoEb2TO'],
    ['customer_id' => [new SqidExists(Customer::class)]],
)->validate();

The rule validates that the sqid can be decoded for the given model and that the model exists.

You can also add query constraints similar to Laravel's Rule::exists:

use RedExplosion\Sqids\Rules\SqidExists;

$rule = (new SqidExists(Post::class))
    ->where('team_id', $team->id)
    ->withoutTrashed();

$validated = validator(
    ['post' => 'pst_A3EyoEb2TO'],
    ['post' => [$rule]],
)->validate();

Available constraints:

where($column, $value)
whereNot($column, $value)
whereNull($column)
whereNotNull($column)
whereIn($column, $values)
whereNotIn($column, $values)
withoutTrashed()
onlyTrashed()

Route model binding

Laravel Sqids supports route model binding out of the box. Simply create a route as you normally would and we'll take care of the rest:

// GET /users/usr_A3EyoEb2TO
Route::get('users/{user}', function (User $user) {
    return "Hello $user->name";
});

Finding a model from a Sqid

One of the most powerful features of Laravel Sqids is being able to resolve a model instance from a given Sqid. This could be incredibly powerful when searching models across your application.

use RedExplosion\Sqids\Model;

$model = Model::find('usr_A3EyoEb2TO');

When we run the following, $user will be an instance of the User model for the given Sqid. If no model could be found, then null will be returned.

if you would like to throw an exception instead, you can use the findOrFail method which will throw an instance of the ModelNotFoundException:

use RedExplosion\Sqids\Model;

$model = Model::findOrFail('usr_A3EyoEb2TO');

Important

In order to use this feature, you must use prefixes for your Sqids.

Testing

composer test

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

If you discover a security vulnerability, please send an e-mail to Ben Sherred via ben@redexplosion.com. All security vulnerabilities will be promptly addressed.

Credits

License

Laravel Sqids is open-sourced software licensed under the MIT license.

red-explosion / laravel-sqids

Maintainers

Package info

Statistics

Security