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 часы для детерминированных тестов.

Коротко

Единый генератор идентификаторов, покрывающий объединение типовых аналогов: все версии UUID (как ramsey/uuid), ULID (как symfony/uid и robinvdvleuten/ulid), NanoID (как hidehalo/nanoid-php), Snowflake и Sonyflake (как godruoyi/php-snowflake) — в одном пакете с криптостойким источником, иммутабельными объектами-значениями и нулевыми зависимостями. Один API вместо пяти библиотек; строгая валидация и PSR-20 часы для детерминированных тестов.

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

Все таблицы ниже сгенерированы автоматически из честных сравнительных тестов (benchmarks/compare.php) на ОДИНАКОВОЙ операции для всех аналогов, PHP 8.1.34, без Xdebug.

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

Возможность	🏆 CloudCastle	ramsey	symfony	ulid	snowflake	nanoid	new¹
UUID RFC 9562 полный набор версий (v1/v3/v4/v5/v6/v7)	✅	✅	✅	❌	❌	❌	❌
ULID (лексикографически сортируемый)	✅	❌	✅	✅	❌	❌	❌
Snowflake / Sonyflake	✅	❌	❌	❌	✅	❌	❌
NanoID	✅	❌	❌	❌	❌	✅	❌
Сортируемые по времени идентификаторы	✅	✅	✅	✅	✅	❌	❌
Всего	🏆 5	2	3	2	2	1	0

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

Свойство	🏆 CloudCastle	ramsey	symfony	ulid	snowflake	nanoid	new¹
CSPRNG-источник случайности по умолчанию	✅	✅	✅	✅	❌	✅	✅
Соответствие RFC 9562 (биты версии/варианта)	✅	✅	✅	❌	❌	❌	✅
Строгая валидация с типизированным исключением	✅	✅	✅	❌	❌	❌	❌
Переполнение-безопасная 64-битная арифметика ID	✅	❌	❌	❌	✅	❌	❌
Монотонность/устойчивость к коллизиям во времени	✅	✅	✅	✅	✅	❌	❌
Всего	🏆 5	4	4	2	2	1	2

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

Генерация одного идентификатора-строки, 100 000 раз (минимум из 4).

Решение	Время (мс)	Итог
new¹	1 427,3	базовый уровень (не библиотека)
🏆 CloudCastle	1 595	быстрейшее среди библиотек
ulid	1 690,1	аналог
symfony	1 758,3	аналог
snowflake	3 453,1	аналог
ramsey	4 078,7	аналог
nanoid	9 643	аналог

4. Потребление памяти

Инкрементальный пик при генерации и удержании 100 000 идентификаторов (изолированный процесс).

Решение	Пиковая память (KB)	Итог
🏆 nanoid	8 788	легчайшее среди библиотек
snowflake	8 793	аналог
ulid	9 589	аналог
symfony	10 415	аналог
ramsey	10 937	аналог
CloudCastle	12 004	аналог
new¹	35 350	базовый уровень (не библиотека)

¹ Базовый уровень (нативные вызовы/примитивы без полноты решения) показан для контекста и не претендует на победу среди библиотек-аналогов.

О памяти честно. Замер — фактически занятая память (memory_get_usage) при удержании 100 000 сгенерированных строк-идентификаторов в изолированном процессе (не транзиентный пик и не базовая память процесса). Более короткие идентификаторы (NanoID ≈21, Snowflake ≈19 символов) естественно легче в удержании, чем 36-символьный канонический UUID; на равном классе UUID CloudCastle чуть тяжелее ramsey/symfony (богаче объектная модель генерации). Утечек нет: генерация без удержания не растит память. Память — единственная ось, где пакет не лидирует; это осознанный компромисс ради функционала, скорости и безопасности, где он уверенно первый.

Плюсы, минусы и когда применять

Сильные стороны:

Функционал = объединение аналогов — UUID v1–v8, ULID, NanoID, Snowflake и Sonyflake в одном пакете (у аналогов — по одному-двум типам). Один API вместо подключения пяти библиотек.
Безопасность — криптостойкий random_bytes() во всех генераторах, строгая валидация с типизированным исключением, переполнение-безопасная 64-битная арифметика ID, монотонность ULID с защитой от отката часов.
Иммутабельность — объекты-значения не меняются после создания; PSR-20 часы дают детерминированные тесты.
Производительность — быстрейшая генерация среди библиотек: UUIDv4 быстрее ramsey, symfony, snowflake и nanoid за счёт нативной сборки байт.
Нулевые зависимости — не тянет фреймворк и сторонние пакеты.

Слабые стороны (честно):

Пиковая память — удержание длинных канонических UUID тяжелее, чем коротких NanoID/Snowflake; это компромисс ради широты функционала (см. заметку выше).
Экосистема — у ramsey/uuid шире интеграции (например, готовые типы Doctrine); здесь их нужно подключать самостоятельно.
Не микропакет — если нужен ровно один тип ID (только NanoID), узкий аналог будет минималистичнее по объёму кода.

Когда применять. Когда в системе используются разные схемы идентификаторов (UUID для сущностей, ULID/Snowflake для сортируемых ключей, NanoID для коротких ссылок) — единый пакет убирает зоопарк зависимостей и даёт один согласованный API с криптостойкостью и строгой валидацией. Для единственного узкого типа ID подойдёт и специализированный аналог.

Разработка

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

Лицензия