Як генерувати короткі та URL-safe ID з чисел за допомогою Sqids

Sqids перетворює одне або кілька невід’ємних цілих чисел на короткий, безпечний для URL рядок і навпаки. Це наступник Hashids, який підтримує понад 40 мов програмування — ID, згенерований у PHP, буде ідентичним для JavaScript, Python чи Rust за однакових налаштувань. Для роботи бібліотеці потрібні PHP 8.1 та розширення gmp або bcmath для точних математичних обчислень.

Типовий сценарій використання — приховування послідовних ключів бази даних у публічних URL. Посилання на кшталт /invoices/1 та /invoices/2 дають користувачам зрозуміти кількість записів і дозволяють легко перебирати їх. Кодування первинного ключа перетворює його на непрозорий рядок.

# Кодування та декодування чисел

Конструктор не потребує обов'язкових аргументів. Передайте масив цілих чисел у метод encode() і отримайте їх назад за допомогою decode():

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

Оскільки один ID може містити кілька чисел, ви можете об’єднувати пов’язані дані (наприклад, ID моделі та ідентифікатор типу) в один токен і розпаковувати їх одним кроком.

# Мінімальна довжина

За замовчуванням ID має мінімально необхідну довжину. Параметр minLength дозволяє створювати рядки фіксованого розміру, що робить ID одноманітними та ускладнює підбір значень:

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

# Власний алфавіт

Алфавіт визначає набір символів в ID та порядок їх перемішування. Власний алфавіт дозволяє створювати унікальні для вашого застосунку ідентифікатори: одні й ті самі числа даватимуть різні результати порівняно зі стандартними налаштуваннями.

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

# Список заборонених слів

Sqids має вбудований список нецензурної лексики й автоматично перекодовує будь-який ID, що містить такі слова. Ви можете замінити цей список власними термінами для фільтрації:

$sqids = new Sqids(blocklist: ['fbmzYm']);
 
// Поверне інший ID, щоб уникнути заблокованого слова
$sqids->encode([7, 8, 9]);

# Коли варто (і не варто) використовувати Sqids

Sqids — це інструмент для кодування, а не шифрування. Результат легко розкодувати, знаючи алфавіт, тому він не підходить для захисту конфіденційних даних або заміни механізмів авторизації.

Бібліотека ідеально підходить для публічних ідентифікаторів, скорочення посилань, пакування кількох чисел в одну мітку для зменшення кількості запитів або для короткочасних токенів (наприклад, посилань для входу). Однак для доступу до приватних даних використовуйте повноцінне шифрування та перевірку прав доступу.

Встановити бібліотеку можна через Composer:

composer require sqids/sqids

Вихідний код та повна документація доступні на GitHub.