Feature Serialization forms

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

← Возможности · Главная · Сравнение

Девять форм ввода-вывода одних и тех же 16 байт — самый широкий набор среди PHP-библиотек, плюс умный fromString(), распознающий форму по длине.

Принцип работы

use CloudCastle\Uuid\Uuid;

$u = Uuid::uuid7();

$u->toString();     // 'c232ab00-9414-…'  каноническая (36)
$u->toBytes();      // 16 сырых байт — BINARY(16)
$u->toHex();        // 32 hex-символа
$u->toBase58();     // 22 символа (совместимо с symfony/uid)
$u->toBase32();     // 26 символов — форма ULID
$u->toUrn();        // 'urn:uuid:c232ab00-…'
$u->toInteger();    // '258338462…' — десятичное 128-битное
$u->toGuidBytes();  // GUID Microsoft (little-endian поля)
$u->toUlid();       // объект Ulid тех же байтов

Разбор — симметричный, плюс умная точка входа:

Uuid::fromString($любаяФорма);   // по длине: 16/22/26/32/36/38/45
Uuid::fromRfc4122($канон);       // строго каноническая
Uuid::fromHex('0x…');            // hex, допускает префикс 0x
Uuid::fromBase58($s22);
Uuid::fromBase32($ulid26);
Uuid::fromInteger($десятичное);
Uuid::fromGuidBytes($guid16);
Uuid::fromUrn('urn:uuid:…');
Uuid::isValid($строка);          // проверка без исключения

Все формы полностью валидируются на входе; управляющие символы в сообщениях ошибок экранируются (безопасно для логов).

Плюсы

• Один объект — все представления: БД, URL, журналы, интеграции с MS-стеком.
• Base58/Base32 совместимы с symfony/uid, URN и десятичная — с ramsey/uuid: пакет читает и пишет «диалекты» обоих.
• Длинная арифметика 128 бит (десятичная форма, Base58) — 32-битными словами, без GMP/BCMath.

Минусы

• Умный fromString() различает формы по длине: hex-строку из ровно 36 символов без дефисов он не примет за hex (это защита, а не недостаток).

✅ Рекомендуется

• toBytes() + BINARY(16) — компактное хранение и быстрые индексы.
• toBase58() — короткие человекочитаемые ссылки без похожих символов.

❌ Антипаттерны

• Хранение канонической строки VARCHAR(36) в больших таблицах — двойной размер против BINARY.

Схема фичи

flowchart TB
    B[("Uuid — 16 байт")]
    B --> S1["toString() 36"] & S2["toHex() 32"] & S3["toBase58() 22"] & S4["toBase32() 26"]
    B --> S5["toUrn() 45"] & S6["toInteger() ≤39"] & S7["toGuidBytes() 16LE"] & S8["toUlid()"]
    F["fromString() — умный разбор по длине"] --> B

Loading

Жизненный цикл

sequenceDiagram
    participant A as Приложение
    participant U as Uuid

    A->>U: fromString(ввод)
    U->>U: длина → форма → полная валидация
    U-->>A: 16 байт (или InvalidIdentifierException)
    A->>U: toBase58() / toBytes() / …
    U-->>A: нужное представление

Loading

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

Возможность	Uuid	ramsey/uuid	symfony/uid	🏆 Победитель
Канон / байты / hex	✅	✅	✅	Паритет
Base58	✅	❌	✅	Uuid + symfony/uid
Base32 (форма ULID)	✅	❌	✅	Uuid + symfony/uid
URN	✅	✅	❌	Uuid + ramsey/uuid
Десятичное 128-битное	✅	✅	❌	Uuid + ramsey/uuid
GUID (little-endian)	✅	✅	❌	Uuid + ramsey/uuid
Умный fromString	✅	❌	✅	Uuid + symfony/uid
Всё вместе в одном классе	✅	❌	❌	Uuid