README

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

CloudCastle Uuid

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

Установка

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/v8)	✅	✅	✅	❌	❌	❌	❌
UUID v2 DCE Security	✅	✅	❌	❌	❌	❌	❌
Nil / Max UUID	✅	✅	✅	❌	❌	❌	❌
ULID (лексикографически сортируемый)	✅	❌	✅	✅	❌	❌	❌
Монотонный ULID	✅	❌	✅	❌	❌	❌	❌
ULID ↔ UUID конвертация	✅	❌	✅	❌	❌	❌	❌
Snowflake	✅	❌	❌	❌	✅	❌	❌
Sonyflake	✅	❌	❌	❌	❌	❌	❌
NanoID с настраиваемым алфавитом	✅	❌	❌	❌	❌	✅	❌
Сортируемые по времени идентификаторы	✅	✅	✅	✅	✅	❌	❌
Base58 / Crockford Base32	✅	❌	✅	✅	❌	❌	❌
GUID byte order	✅	✅	❌	❌	❌	❌	❌
PSR-20 инъекция часов	✅	❌	✅	❌	❌	❌	❌
Инъекция источника случайности	✅	✅	❌	❌	✅	✅	❌
Иммутабельные объекты-значения	✅	✅	✅	❌	❌	❌	❌
Всего	🏆 15	7	9	3	3	2	0

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

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

2.1. Стандарты безопасности composer-пакетов

Стандарт	🏆 CloudCastle	ramsey	symfony	ulid	snowflake	nanoid	new¹
SECURITY.md политика раскрытия	✅	✅	✅	❌	❌	❌	❌
Packagist / FriendsOfPHP security advisories	✅	✅	✅	✅	✅	✅	❌
composer audit в CI	✅	❌	✅	❌	❌	❌	❌
Статанализ безопасности в CI	✅	✅	✅	❌	❌	❌	❌
CSPRNG по умолчанию (CWE-338)	✅	✅	✅	✅	❌	✅	✅
Строгое сравнение идентификаторов (CWE-208)	✅	✅	✅	❌	❌	❌	❌
Валидация ввода на границе API	✅	✅	✅	❌	❌	❌	❌
Всего	🏆 7	6	🏆 7	2	1	2	1

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

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

Решение	Время (мс)	Итог
🏆 CloudCastle	89,2	быстрейшее среди библиотек
symfony	96,5	аналог
new¹	96,9	базовый уровень (не библиотека)
ramsey	157,9	аналог
nanoid	186,7	аналог
ulid	359,3	аналог
snowflake	1 180,5	аналог

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

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

Решение	Пиковая память (KB)	Итог
🏆 nanoid	8 788	легчайшее среди библиотек
snowflake	8 793	аналог
ulid	9 587	аналог
symfony	10 408	аналог
ramsey	10 895	аналог
CloudCastle	11 999	аналог
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 за счёт нативной сборки байт.
Нулевые зависимости — не тянет фреймворк и сторонние пакеты.

Слабые стороны (честно — только допустимые):

Возраст и распространённость — пакет моложе и менее известен, чем ramsey/uuid / symfony/uid; меньше звёзд и установок на Packagist.
Пиковая память — удержание длинных канонических UUID тяжелее коротких NanoID/Snowflake; осознанный компромисс ради функционала и скорости (см. заметку выше). Иных минусов нет.

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

Разработка

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

Лицензия