Architecture

🏗️ Архитектура

Главная · Возможности

Слои пакета

flowchart TB
    subgraph Contract["Contract — контракты"]
        II[IdentifierInterface]
        TBI[TimeBasedIdentifierInterface]
        RSI[RandomSourceInterface]
    end

    subgraph Exception["Exception — исключения"]
        IEI[IdentifierExceptionInterface]
        IIE[InvalidIdentifierException]
    end

    subgraph Core["Ядро"]
        direction TB
        VO["Объекты-значения:<br/>Uuid · Ulid · SnowflakeId · SonyflakeId"]
        FA["Фабрики:<br/>UuidFactory · UlidFactory ·<br/>SnowflakeFactory · SonyflakeFactory · NanoIdFactory"]
        CO["Кодеки:<br/>Base58 · CrockfordBase32 · ByteMath · UnixTime"]
        EN["Enum-настройки:<br/>UuidNamespace · UuidVariant · UuidDceDomain"]
    end

    PSR["psr/clock (единственная runtime-зависимость)"] --> FA
    Contract --> Core
    Core --> Exception

Loading

Правила зависимостей закреплены в deptrac.yaml и проверяются в CI: контракты ни от чего не зависят, исключения — только от контрактов, ядро — от контрактов и исключений.

Ключевые решения

Байтовая модель значений. Каждый объект-значение хранит канонические байты (16 у Uuid/Ulid, 8 у *flake). Все текстовые формы — проекции этих байтов; toBytes(), equals(), compareTo() и мост UUID↔ULID не требуют перекодирования. Обратная сторона: разбор строки сразу материализует и валидирует байты (см. честное сравнение с ленивыми парсерами в Comparison).

Иммутабельность. Все VO — final с private readonly-состоянием и приватным конструктором; создание — только через фабричные методы с полной валидацией (или доверенный внутренний путь для генераторов).

Монотонное состояние в фабриках, не в значениях. UuidFactory (v1/v6/v7), UlidFactory и *flake-фабрики несут счётчики и метки последней выдачи; сами значения — чистые данные.

Быстрый системный путь. Без PSR-часов фабрики читают microtime() напрямую — абстракция времени не стоит ничего, пока не нужна.

Дробление God-объекта. Uuid собран из четырёх трейтов (разбор, сериализация, временные поля, шорткаты) — каждый файл обозрим, метрики PHPMD соблюдены без ослабления конфига.

Структура каталогов

src/
├── Contract/            # интерфейсы (PSR-стиль)
├── Exception/           # иерархия исключений
├── Uuid.php             # VO + 4 трейта рядом
├── Ulid.php
├── SnowflakeId.php  SonyflakeId.php
├── *Factory.php         # генераторы
├── Base58.php  CrockfordBase32.php  ByteMath.php
└── UnixTime.php  UuidNamespace.php  UuidVariant.php  UuidDceDomain.php
tests/                   # unit / integration / security / load / performance
tools/                   # бенчмарки, генераторы документации, пороги
wiki/                    # исходники этой документации