README

Laravel wrapper for Sqids

Laravel Wrapper for sqids.org PHP library.

Support us

Your support is key to the continual advancement of our plugin. We appreciate every user who has contributed to our journey so far.

While our plugin is available for all to use, if you are utilizing it for commercial purposes and believe it adds significant value to your business, we kindly ask you to consider supporting us through GitHub Sponsors. This sponsorship will assist us in continuous development and maintenance to keep our plugin robust and up-to-date. Any amount you contribute will greatly help towards reaching our goals. Join us in making this plugin even better and driving further innovation.

Installation

You can install the package via composer:

composer require guava/sqids-for-laravel

Usage

This package adds a slightly modified version of the Sqids class, which allows a fluent configuration of all options. It also adds a salting option.

Generating Sqids

There's multiple ways you can use this package to generate sqids:

// Via our Facade
use Guava\Sqids\Facades\Sqids;

Sqids::encode([1,2,3]); /// Outputs '86Rf07'



// Via a classic instance
use Guava\Sqids\Sqids;
$sqids = new Sqids();
$sqids->encode([1,2,3]); /// Outputs '86Rf07'



// Via the app container / dependency injection
use Guava\Sqids\Sqids;
app(Sqids::class)->encode([1,2,3]); /// Outputs '86Rf07'



// Via our factory method, which simply returns an instance of Sqids
// The factory method is also available on the facade class
use Guava\Sqids\Sqids;
Sqids::make()->encode([1,2,3]);

It's entirely up to you which way you prefer. In our examples, we will make use of the factory method.

Using in Eloquent Models

This package also comes with a trait that you can use in your Eloquent models. This trait will automatically add a sqid attribute which will be created from the model's primary key.

use \Illuminate\Database\Eloquent\Model;
use \Guava\Sqids\Concerns\HasSqids;

class YourModel extends Model {
    use HasSqids;
    
    // ...
}

That's it! Now you can access the sqid attribute on your model.

You can custimize how the sqid on your model is generated by overriding the getSqids method:

use \Illuminate\Database\Eloquent\Model;
use \Guava\Sqids\Concerns\HasSqids;
use \Guava\Sqids\Sqids;

class YourModel extends Model {
    use HasSqids;
    
    // ...
    
    protected function getSqids(): Sqids
    {
        return Sqids::make()
            ->salt() // This will use the model's class name as the salt, so every model generates different IDs
             // ... add more options here
        );
    }
}

Route binding

If you want to be able to use the sqid as the route key, simply add the HasSqidsRouting trait to your model:

use \Illuminate\Database\Eloquent\Model;
use \Guava\Sqids\Concerns\HasSqids;
use \Guava\Sqids\Concerns\HasSqidsRouting;

class YourModel extends Model {
    use HasSqids, HasSqidsRouting;
    
    // ...
}

Options

Customizing the alphabet

use Guava\Sqids\Sqids;

Sqids::make()
->alphabet('0123456789abcdef')
->encode([1,2,3]); /// Outputs '489158'

Customizing the minLength

use Guava\Sqids\Sqids;

Sqids::make()
->minLength(8)
->encode([1,2,3]); /// Outputs '86Rf07xd'

Customizing the block list

use Guava\Sqids\Sqids;

Sqids::make()
->blocklist(['86Rf07'])
->encode([1,2,3]); /// Outputs 'se8ojk'

Salting

Salting can be used to generate different IDs based on the provided salt, which can be any string or integer.

use Guava\Sqids\Sqids;

Sqids::make()
->salt('my-salt')
->encode([1,2,3]); /// Outputs 'MNtmFG'

Salting is especially useful on models, when you want every model to return different IDs: a record of Model1 with the ID 1 then has a different sqid than a record of Model2 with the ID 1.

Called without a value, salt() uses the model's morph class: its class name, or its alias when you have a morph map.

use \Illuminate\Database\Eloquent\Model;
use \Guava\Sqids\Concerns\HasSqids;
use \Guava\Sqids\Sqids;

class YourModel extends Model {
    use HasSqids;
    
    // ...
    
    protected function getSqids(): Sqids
    {
        return Sqids::make()
            ->salt() // The model's morph class is the salt, so every model generates different IDs
        ;
    }
}

Important

A salt must never change once sqids are in links, e-mails or a database column: a different salt gives different sqids. A class name changes when the model is renamed or moved, so pass a fixed salt (->salt('your-model')) or use a morph map when that can happen.

Salting does not use PHP's random number generator: a salt gives the same sqids on every PHP version, and rand(), shuffle() and friends are left untouched.

Storing the sqid in a column

HasSqids computes the sqid on every read, so the database knows nothing about it. When you need to search by it (by prefix too), join on it or read it from outside the app, store it in a column with the HasStoredSqids trait, used in place of HasSqids and HasSqidsRouting:

use \Illuminate\Database\Eloquent\Model;
use \Guava\Sqids\Concerns\HasStoredSqids;

class YourModel extends Model {
    use HasStoredSqids;
    
    // ...
}

The ID is known only after the insert, so the column is filled right after the model is created. Make it nullable, with a unique index:

$table->string('sqid')->nullable()->unique();

The sqid is the model's route key, looked up in the column, so only the stored sqid finds the model. Everything can be customized:

class Ticket extends Model {
    use HasStoredSqids;

    // The column the sqid is stored in ('sqid' by default)
    public function getSqidColumn(): string
    {
        return 'code';
    }

    // Brings a sqid from a URL to the form it is stored in
    public function normalizeSqid(string $sqid): string
    {
        return strtoupper(trim($sqid));
    }

    protected function getSqids(): Sqids
    {
        return Sqids::make()
            ->alphabet('ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789')
            ->minLength(5)
            ->salt('ticket')
        ;
    }
}

Rows inserted without model events (bulk inserts, seeders using WithoutModelEvents) or before the column existed get no sqid. Fill them with:

Ticket::backfillSqids(); // Returns the number of rows filled

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

Lukas Frey
All Contributors
Spatie - Our package skeleton is a modified version of Spatie's Package Skeleton
https://github.com/mtvs/eloquent-hashids

License

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

guava / sqids-for-laravel

Package info

Security

Fund package maintenance!

Statistics