How Sqids Generates Short, URL‑Safe IDs and When to Use Them

What is Sqids?

Sqids is an open‑source library that generates short, unique, URL‑safe identifiers from one or more non‑negative integers. The identifiers can be decoded back to the original numbers and avoid common profanity.

Use cases

Typical applications include link shortening, generating unique event IDs for logs, creating product or object IDs on a website (similar to YouTube video IDs), short IDs for text messages, email confirmation codes, and more.

What it is not suitable for

Sqids should not be used for sensitive data. The generated IDs are not cryptographic hashes and can be decoded, so they may expose the total number of users if used as user IDs.

Can it encode multiple numbers?

Yes. Sqids can encode any number of non‑negative integers into a single ID. The count of numbers is unlimited, though the size of each number may be limited by the language implementation. This enables encoding timestamps for expiring IDs or combining a database shard number with a primary key to reduce extra queries.

Are the generated IDs unique?

For a given input array and alphabet, the ID is unique. The default alphabet contains both uppercase and lowercase letters, making IDs case‑sensitive.

Limitations

Negative numbers cannot be encoded.

The alphabet must contain at least three characters.

The alphabet cannot include multibyte characters.

Sqids cannot generate IDs of an exact length; it can only guarantee a minimum length (0‑255).

If the desired length cannot be reached, the algorithm may retry with a reduced alphabet.

Installation & Examples

Installation

composer require sqids/sqids

Examples

1. Simple encode and decode

$sqids = new Sqids();
$id = $sqids->encode([1, 2, 3]); // "86Rf07"
$numbers = $sqids->decode($id); // [1, 2, 3]

Note: Because of the algorithm design, different IDs can decode to the same number sequence. If canonical IDs are required, re‑encode the decoded numbers and verify the generated ID matches.

2. Enforcing a minimum length

$sqids = new Sqids(minLength: 10);
$id = $sqids->encode([1, 2, 3]); // "86Rf07xd4z"
$numbers = $sqids->decode($id); // [1, 2, 3]

3. Custom alphabet for randomised IDs

$sqids = new Sqids(alphabet: 'FxnXM1kBN6cuhsAvjW3Co7l2RePyY8DwaU04Tzt9fHQrqSVKdpimLGIJOgb5ZE');
$id = $sqids->encode([1, 2, 3]); // "B4aajs"
$numbers = $sqids->decode($id); // [1, 2, 3]

4. Blocking specific words

$sqids = new Sqids(blocklist: ['86Rf07']);
$id = $sqids->encode([1, 2, 3]); // "se8ojk"
$numbers = $sqids->decode($id); // [1, 2, 3]

For more details, see the GitHub repository: https://github.com/sqids/sqids-php