lava83/laravel-sqid

A thin Laravel integration for Sqids: encode lists of integers into short, URL-friendly strings and decode them back, configurable via alphabet, min_length and blocklist.

v0.1.4 2026-06-10 09:09 UTC

Requires

• php: ^8.3
• illuminate/contracts: ^12.0||^13.0
• spatie/laravel-package-tools: ^1.16
• sqids/sqids: ^0.5.0

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.14
• nunomaduro/collision: ^8.8
• orchestra/testbench: ^11.0.0||^10.0.0||^9.0.0
• pestphp/pest: ^4.0
• pestphp/pest-plugin-arch: ^4.0
• pestphp/pest-plugin-laravel: ^4.0
• phpstan/extension-installer: ^1.4
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-phpunit: ^2.0

MIT

• Stefan Riedel

• encode
• decode
• laravel
• sqids
• url-friendly
• Lava83
• laravel-sqid

README

A thin, idiomatic Laravel integration for Sqids. It encodes lists of integers into short, URL-friendly strings and decodes them back, configurable via alphabet, min_length and blocklist.

Note: Sqids are not sequential, sortable or cryptographically secure, and they are not meant to replace database primary keys. They obfuscate integers into compact, unguessable-looking strings — for example to expose internal IDs in URLs without leaking the raw values.

use Lava83\LaravelSqid\Facades\LaravelSqid;

LaravelSqid::encode([1, 2, 3]);   // "86Rf07"
LaravelSqid::decode('86Rf07');    // Collection: [1, 2, 3]

Requirements

• PHP ^8.3
• Laravel 12 or 13 (illuminate/contracts ^12.0||^13.0)

Installation

Install the package via Composer:

composer require lava83/laravel-sqid

The service provider and the LaravelSqid facade are registered automatically via package discovery.

Optionally publish the config file:

php artisan vendor:publish --tag="laravel-sqid-config"

Configuration

The published config/sqid.php looks like this:

use Sqids\Sqids;

return [
    'min_length' => env('LARAVEL_SQID_MIN_LENGTH', Sqids::DEFAULT_MIN_LENGTH),
    'alphabet' => env('LARAVEL_SQID_ALPHABET', Sqids::DEFAULT_ALPHABET),
    'blocklist' => env('LARAVEL_SQID_BLOCKLIST', Sqids::DEFAULT_BLOCKLIST),
];

All three options can be driven by environment variables:

ENV variable	Config key	Description
LARAVEL_SQID_MIN_LENGTH	min_length	Minimum length of the generated Sqid string.
LARAVEL_SQID_ALPHABET	alphabet	Custom alphabet used for encoding.
LARAVEL_SQID_BLOCKLIST	blocklist	Words that must not appear in any generated Sqid string.

The underlying Sqids\Sqids instance is bound in the container from this config, so customizing the config is all you need.

Usage

Facade

use Lava83\LaravelSqid\Facades\LaravelSqid;

// Encode an array or a Collection of integers
LaravelSqid::encode([1, 2, 3]);          // "86Rf07"
LaravelSqid::encode(collect([1, 2, 3])); // "86Rf07"

// Decode back into a Collection<int>
LaravelSqid::decode('86Rf07');           // collect([1, 2, 3])

Helpers

Global helper functions are available everywhere:

sqid_encode([1, 2, 3]);   // "86Rf07"
sqid_decode('86Rf07');    // collect([1, 2, 3])

Collection macro

A sqidsEncode() macro is mixed into Illuminate\Support\Collection:

collect([1, 2, 3])->sqidsEncode(); // "86Rf07"

Encoding only accepts integers

encode() (and therefore the helper and the collection macro) only accepts integers. Anything else throws an OnlyIntegersCanBeSqidEncoded exception:

use Lava83\LaravelSqid\Exceptions\OnlyIntegersCanBeSqidEncoded;

LaravelSqid::encode([1, 2, 'foo']); // throws OnlyIntegersCanBeSqidEncoded

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

• Stefan Riedel
• All Contributors

License

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