README

Все идентификаторы для PHP 8.1+ в одном пакете: UUID версий 1–8 (RFC 9562), ULID, NanoID, Snowflake и Sonyflake. PSR-20 часы во всех временных генераторах, девять форм сериализации, жёсткая валидация ввода — функциональный суперсет пяти сравниваемых библиотек.

Установка

composer require cloudcastle/uuid

Требуется PHP 8.1+. Единственная runtime-зависимость — интерфейс psr/clock.

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

<?php

use CloudCastle\Uuid\{Uuid, Ulid, NanoIdFactory, SnowflakeFactory};

// UUID: случайный и сортируемый.
Uuid::uuid4()->toString();            // 'e2b0dd0e-1c2d-4f6a-…'
Uuid::uuid7()->toBytes();             // 16 байт → BINARY(16), порядок = порядку создания

// Разбор любой формы: канон / hex / Base58 / ULID-форма / URN / байты.
$uuid = Uuid::fromString($input);     // мусор → типизированное исключение
$uuid->toBase58();                    // короткая ссылка
$uuid->toUlid();                      // мост в ULID без перекодирования

// Другие семейства.
Ulid::generate()->toString();               // '01ARYZ6S41…' — монотонный ULID
(new NanoIdFactory())->generate();          // 'V1StGXR8_Z5jdHi6B-myT'
(new SnowflakeFactory(1, 7))->generate();   // BIGINT для распределённых систем

// Киллер-фича: детерминизм в тестах — PSR-20 часы во ВСЕХ генераторах.
use CloudCastle\Clock\MockClock;
use CloudCastle\Uuid\UuidFactory;

$factory = new UuidFactory(clock: MockClock::from('2026-01-01 00:00:00', 'UTC'));
$factory->uuid7()->timestampMs();     // ровно 1767225600000 — в каждом прогоне

Больше сценариев — в wiki: на каждую возможность есть отдельная страница с примерами и сравнением с аналогами.

Возможности

Все версии UUID (v4, v7, v1/v6, v3/v5, v2 DCE, v8, Nil/Max), девять форм сериализации, ULID с мостом в UUID, NanoID, Snowflake, Sonyflake и полный детерминизм в тестах: функционально пакет покрывает возможности всех пяти сравниваемых аналогов вместе взятых.

Сводное сравнение с аналогами (генерируется автоматически из tools/features-data.php, победитель вычисляется по фактам поддержки):

Сгенерировано из tools/features-data.php (факты о поддержке). Легенда: ✅ полностью · ⚠️ частично · 🔌 адаптер · ❌ нет · — неприменимо.

Версии UUID (RFC 9562)

Формы сериализации UUID

ULID

NanoID

Snowflake и Sonyflake

Тестируемость и источники

Зависимости и вес

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

Замеры генерируются автоматически из composer compare: каждая пара «библиотека × сценарий» выполняется в отдельном PHP-процессе (память одной библиотеки не влияет на замеры другой), одинаковые циклы для всех, медиана из 7 прогонов, Xdebug выключен. Отрыв лидера меньше 2 % честно помечается как «Паритет лидеров».

Память меряется с байтовой точностью в тех же изолированных процессах: добавленная пиковая память за сценарий. Дополнительно потребление памяти самого пакета контролируется нагрузочными тестами (tests/Load — бюджеты на 100 000+ операций).

Сгенерировано из composer compare (PHP 8.1.34). Правки в блоке будут перезаписаны.

Память — добавленная пиковая память процесса за сценарий (классы библиотеки + объекты + операции), меньше — лучше:

Качество

Пороги ниже проставляются автоматически из конфигов пакета при генерации документации (composer docs:sync):

Сгенерировано из конфигов проекта — правьте infection.json.dist / phpmd.xml / tools/coverage-check.php / composer.json, не таблицу.

Строгость контроля качества против аналогов (значения — из конфигов, автоматически):

Сгенерировано из конфигов пакета (composer docs:sync). Уровни Uuid — из phpstan.neon / psalm.xml / infection.json.dist / phpmd.xml / deptrac.yaml; по аналогам — заявленный инструментарий из их composer.json (Composer-дистрибутивы аналогов конфигов качества не содержат, поэтому их уровни — «н/д»).

composer ci        # полный пайплайн качества
composer check     # быстрые проверки перед коммитом
composer test      # тесты (unit + integration + security + load + performance)

Заключение: когда что выбирать

Сильные стороны cloudcastle/uuid — пять семейств идентификаторов в одном пакете (единственная библиотека с UUID 1–8, ULID, NanoID, Snowflake и Sonyflake сразу), PSR-20 часы и подменяемая случайность во всех генераторах (байт-в-байт воспроизводимая генерация в тестах), девять форм сериализации, читающих «диалекты» и ramsey (URN, десятичная, GUID), и symfony (Base58, Base32), байтовая модель значений с мгновенным toBytes() и жёсткая граница ввода с экранированием управляющих символов в ошибках.

Производительность: лидер в 11 из 13 сценариев — NanoID ×2.7 к hidehalo, Snowflake ×6.8 и разбор ×2.6 к godruoyi, Base58 ×2.7 и UUID v5 +59 % к symfony, v7 +18 %, генерация ULID +6 % до строки и +128 % до 16 байт. Два сценария честно уступают ленивым парсерам: ramsey при «разборе строки» возвращает обёртку без немедленного декодирования (наш разбор сразу материализует и валидирует байты), robinvdvleuten хранит подстроки ULID без декода и проверки диапазона. Память: 0.0 КБ добавленной пиковой во всех сценариях (байтовая точность).

Слабые стороны — пакет моложе конкурентов; экосистемные интеграции (Doctrine-типы, Symfony-нормализаторы) пока отдельными пакетами не поставляются.

Честные рекомендации:

• Нужны несколько семейств идентификаторов, тестируемость времени, BINARY-хранение — cloudcastle/uuid: всё в одном пакете.
• Глубокая экосистема Doctrine/legacy вокруг только UUID — ramsey/uuid.
• Проект на Symfony, нужен UUID/ULID со строковым выводом — symfony/uid.
• Минимальный ULID без бинарной формы — robinvdvleuten/ulid.
• Только NanoID — hidehalo/nanoid-php.
• Snowflake с Redis/Laravel-резолвером — godruoyi/php-snowflake.

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

• Wiki — руководство пользователя
• Возможности — страница на каждую фичу
• Сравнение с аналогами
• Архитектура — схемы работы пакета
• API-документация

Контакты

• Email — alex-4-17@yandex.ru
• VK — https://vk.com/leha_zorin
• Telegram — @CloudCastle85
• Телефон — +79872763991
• Сетка — https://set.ki/LdYRz76

Поддержать проект

Реквизиты для поддержки автора — в DONATE.md.

Contributors

Спасибо всем, кто вносит вклад в проект: