Feature Uuid v7

📈 UUID v7 — сортируемый

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

48 бит миллисекунд Unix + 12-битный монотонный счётчик + 62 случайных бита: лексикографический порядок совпадает с порядком создания — идеальный первичный ключ.

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

use CloudCastle\Uuid\Uuid;

$a = Uuid::uuid7();
$b = Uuid::uuid7();

$a->compareTo($b);        // -1 — всегда, даже в одну миллисекунду
$a->timestampMs();        // миллисекунды Unix из идентификатора
$a->dateTime();           // DateTimeImmutable (UTC)

Внутри одной миллисекунды растёт счётчик в поле rand_a (RFC 9562 §6.2); при 4096 значениях за миллисекунду генерация переносится в следующую. Откат системных часов не ломает монотонность — фабрика продолжает от последней выданной метки.

Явный момент — для миграций и бэкфила:

$uuid = (new UuidFactory())->uuid7(new DateTimeImmutable('2020-05-01 12:00:00 UTC'));

Плюсы

• Строгая монотонность в пределах фабрики — вставки в конец индекса.
• Метка времени извлекается без внешних данных.
• С MockClock значения полностью воспроизводимы.

Минусы

• Раскрывает момент создания — для публичных токенов лучше v4.

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

• Первичные ключи БД (вместе с toBytes() в BINARY(16)).
• Событийные журналы, где важен порядок без отдельной колонки времени.

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

• Несколько независимых фабрик в одном процессе «для скорости» — монотонность гарантируется в пределах одной фабрики; используйте UuidFactory::default().

Схема фичи

flowchart LR
    C["PSR-20 часы<br/>или microtime()"] -->|мс Unix 48 бит| F[UuidFactory]
    R[RandomSource] -->|"rand_b 62 бита"| F
    F -->|"счётчик rand_a 12 бит<br/>монотонность"| U[Uuid v7]

Loading

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

sequenceDiagram
    participant A as Приложение
    participant F as UuidFactory

    A->>F: uuid7()
    F->>F: мс совпала с прошлой?
    alt новая миллисекунда
        F->>F: пересеять счётчик (11 бит случайности)
    else та же миллисекунда
        F->>F: счётчик + 1 (переполнение → мс + 1)
    end
    F-->>A: Uuid v7 — строго больше предыдущего

Loading

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

Возможность	Uuid	ramsey/uuid	symfony/uid	🏆 Победитель
Генерация v7	✅	✅	✅	Паритет
Монотонность внутри мс	✅	✅	✅	Паритет
PSR-20 часы	✅	❌	❌	Uuid
Явный момент генерации	✅	✅	✅	Паритет
Скорость генерации до строки	🥇	🥉	🥈	Uuid