README

🇷🇺 Русский · 🇬🇧 English · 🇩🇪 Deutsch · 🇫🇷 Français · 🇪🇸 Español · 🇮🇹 Italiano

CloudCastle Uuid

Единый генератор идентификаторов для PHP 8.1+: UUID v1–v8, монотонный ULID, NanoID, Snowflake и Sonyflake в одном пакете. Криптостойкий источник случайности, иммутабельные объекты-значения, нулевые внешние зависимости.

Установка

composer require cloud-castle/uuid

Требуется PHP 8.1+.

Быстрый старт

<?php

use CloudCastle\Uuid\Uuid;
use CloudCastle\Uuid\Ulid;
use CloudCastle\Uuid\NanoIdFactory;
use CloudCastle\Uuid\SnowflakeFactory;

// UUID — все версии RFC 9562.
$v4 = Uuid::uuid4();                       // случайный
$v7 = Uuid::uuid7();                       // сортируемый по времени
echo $v4->toString();                      // «0189f8b2-…-…»
echo $v4->toBase58();                      // компактная форма
$parsed = Uuid::fromString($v4->toString());

// ULID — 26 символов Crockford Base32, монотонный в пределах миллисекунды.
$ulid = Ulid::generate();
echo $ulid->toString();                    // «01J9Z…»

// NanoID — короткий URL-безопасный идентификатор.
$nano = NanoIdFactory::default()->generate();          // 21 символ
$short = NanoIdFactory::default()->generate(size: 10);

// Snowflake — 64-битный сортируемый ID (Twitter).
$snowflake = (new SnowflakeFactory(datacenterId: 1, workerId: 1))->generate();
echo $snowflake->toInt();

Возможности

UUID v1–v8 (RFC 9562): время (v1/v6), DCE Security (v2), имя-MD5/SHA-1 (v3/v5), случайный (v4), Unix-время (v7), произвольный (v8).
ULID с гарантией монотонности (инкремент случайной части в пределах миллисекунды по спецификации ulid/spec) и защитой от отката часов.
NanoID с настраиваемым алфавитом и длиной, Snowflake (Twitter) и Sonyflake (Sony) — сортируемые 64-битные идентификаторы.
Представления: каноническое, hex, URN, Base58, Crockford Base32, десятичное, GUID-байты; взаимная конвертация ULID ↔ UUID (1:1 по байтам).
Интроспекция: версия, вариант, метка времени, узел; порядковое сравнение.
Безопасность: криптостойкий random_bytes() во всех генераторах, иммутабельные объекты-значения, PSR-20 часы для детерминированных тестов.

Сравнение с аналогами

Сравнение с пятью популярными аналогами по четырём осям. Интероперабельность подтверждена tests/Integration/CompetitorInteroperabilityTest.php; производительность и память измерены в изолированных процессах (минимум из пяти прогонов, PHP 8.1, без Xdebug). Ни один аналог не покрывает все семейства идентификаторов сразу — CloudCastle Uuid делает это в одном пакете.

Функциональность

Тип идентификатора	🏆 CloudCastle	ramsey/uuid	symfony/uid	robinvdvleuten/ulid	hidehalo/nanoid-php	godruoyi/php-snowflake
UUID v1–v8	✅ все 8	✅ все 8	⚠️ без v2	❌	❌	❌
ULID (монотонный)	✅	❌	✅	⚠️ без монотоники	❌	❌
NanoID	✅	❌	❌	❌	✅	❌
Snowflake / Sonyflake	✅ оба	❌	❌	❌	❌	⚠️ только Snowflake
Base58 / Crockford Base32	✅	⚠️ частично	⚠️ частично	❌	❌	❌
Внешние зависимости	✅ 0	несколько	0	0	0	0
Охват семейств ID	🏆 полный	только UUID	UUID + ULID	только ULID	только NanoID	только Snowflake

Производительность

Операция	🏆 CloudCastle	symfony/uid	ramsey/uuid	robinvdvleuten/ulid
UUID v4 (генерация + строка), 500 000×	🏆 438 мс	482 мс	804 мс	—
ULID (генерация + строка, монотонно), 300 000×	🏆 884 мс	905 мс	—	1 076 мс
Итог	🏆 быстрейший	−9 % / −2 %	в 1,8× медленнее	в 1,2× медленнее

_{ULID CloudCastle обгоняет конкурентов, сохраняя монотонность (защиту
сортировки), которой нет у robinvdvleuten и которая обычно замедляет генерацию.}

Безопасность и корректность

Свойство	🏆 CloudCastle	ramsey/uuid	symfony/uid	robinvdvleuten/ulid	hidehalo/nanoid-php
Криптостойкий источник (`random_bytes`)	✅	✅	✅	✅	✅
Монотонность ULID (защита порядка)	✅	❌	✅	❌	❌
Защита от отката часов (ULID/Snowflake)	✅	❌	⚠️	❌	❌
Иммутабельные объекты-значения	✅	✅	✅	⚠️	❌ (строка)
Валидация формы при разборе	✅	✅	✅	✅	n/a
PSR-20 часы для детерминизма тестов	✅	❌	⚠️	❌	❌
Итог	🏆 максимум	средний	высокий	низкий	базовый

Использование памяти

Пакет	Память на объект (UUID v4)	Пиковый footprint (100k)	Итог
🏆 CloudCastle	158 Б	6 935 KB	самый лёгкий объект
symfony/uid	174 Б	6 935 KB	+10 % на объект
ramsey/uuid	208 Б	7 070 KB	+32 % на объект

_{Объект CloudCastle хранит ровно 16 байт и форматирует строку по требованию;
symfony кэширует готовую 36-символьную строку (отсюда больший объект).}

Вывод: CloudCastle Uuid — единственный пакет, объединяющий UUID, ULID, NanoID, Snowflake и Sonyflake, и при этом самый быстрый (UUID v4 и монотонный ULID), самый лёгкий по памяти на объект и с нулевыми внешними зависимостями.

Разработка

composer install
composer check    # линтеры + статический анализ + тесты
composer fix      # автоисправления (Rector, PHP CS Fixer, PHPCBF)
composer ci       # полный CI-пайплайн локально

Полный список команд с описаниями: composer run-script --list.

Документация

Репозиторий: https://gitverse.ru/cloud-castle/uuid
История изменений: CHANGELOG.md
Как внести вклад: CONTRIBUTING.md
Кодекс поведения: CODE_OF_CONDUCT.md
Политика безопасности: SECURITY.md

Лицензия