Generate Short, URL-Safe IDs From Numbers With Sqids

Sqids encodes one or more non-negative integers into a short, URL-safe string and decodes that string back into the original numbers. It's the successor to Hashids, and the same encoding is supported in more than 40 languages, so an ID generated in PHP decodes the same way in JavaScript, Python, or Rust with matching settings. The PHP package requires PHP 8.1 and either the gmp or bcmath extension for its arbitrary-precision math.

A common use is hiding sequential database keys in public URLs. Exposing /invoices/1 and /invoices/2 tells visitors how many records you have and invites them to walk the range. Encoding the primary key first turns it into an opaque string instead.

Encoding and decoding numbers

The constructor takes no required arguments. Pass an array of integers to encode() and read them back with decode():

use Sqids\Sqids;
 
$sqids = new Sqids();
 
$id = $sqids->encode([7, 8, 9]); // "ylrR3H"
$numbers = $sqids->decode($id);  // [7, 8, 9]

Because a single ID can hold several numbers, you can pack related values into one token, such as a model ID and a type discriminator, and unpack them in one step on the way back.

Padding to a minimum length

By default, an ID is only as long as it needs to be, so small numbers produce very short strings. Set minLength to pad every ID up to a fixed size, which keeps generated IDs uniform and makes short, guessable values harder to stumble upon:

$sqids = new Sqids(minLength: 12);
 
$sqids->encode([7, 8, 9]); // "ylrR3HjJRet1"

Custom alphabet

The alphabet determines which characters appear in an ID and the order in which they are shuffled. Supplying your own changes the output and acts as a basic per-application scrambling, so the same numbers produce different IDs than they would with the default alphabet:

$sqids = new Sqids(
    alphabet: 'k3G7QAe51FCsPW92uEOyq4Bg6Sp8YzVTmnU0liwDdHXLajZrfxNhobJIRcMvKt',
);
 
$sqids->encode([7, 8, 9]); // "fbmzYm"

Blocklist

Sqids ships with a built-in list of common profanity and re-encodes any ID that would contain one of those words, so generated IDs avoid them automatically. You can replace the list with your own terms when you want to filter for something specific:

$sqids = new Sqids(blocklist: ['fbmzYm']);
 
// Returns a different ID that avoids the blocked word
$sqids->encode([7, 8, 9]);

When to use Sqids (and when not to)

Sqids is an encoder, not an encryption tool. The output is reversible by anyone who knows the alphabet, so it should not protect sensitive data or serve as a substitute for authorisation checks.

It's a fit for public-facing identifiers and link shortening, encoding database primary keys, packing a few integers into a single reference to reduce lookups, and for short-lived tokens such as one-time login links. It's the wrong tool for anything that must stay secret, for personal or sensitive data, and for access control. For those, reach for real encryption and proper authorisation instead.

Install it with Composer: