Examples

💡 Примеры

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

Практические сценарии применения пакета. Каждый пример самодостаточен.

Первичный ключ BINARY(16) с сортировкой по времени

use CloudCastle\Uuid\Uuid;

// вставка
$uuid = Uuid::uuid7();
$stmt = $pdo->prepare('INSERT INTO orders (id, total) VALUES (?, ?)');
$stmt->execute([$uuid->toBytes(), 990]);

// чтение
$row = $pdo->query('SELECT id FROM orders ORDER BY id DESC LIMIT 1')->fetch();
$last = Uuid::fromBytes($row['id']);
$last->dateTime()->format('Y-m-d H:i');   // время создания — прямо из ключа

ULID в URL, UUID в БД — одно значение

use CloudCastle\Uuid\{Uuid, Ulid};

$uuid = Uuid::uuid7();                       // в БД: $uuid->toBytes()
$url = '/orders/' . $uuid->toUlid()->toLower();  // /orders/01aryz6s41…

// обратно из маршрута
$fromUrl = Ulid::fromString($routeParam)->toUuid();

Валидация пользовательского ввода на границе

use CloudCastle\Uuid\Uuid;
use CloudCastle\Uuid\Exception\InvalidIdentifierException;

try {
    $id = Uuid::fromString($request->query('id'));
} catch (InvalidIdentifierException $e) {
    // сообщение безопасно для логов: управляющие символы экранированы
    $logger->warning('Некорректный идентификатор', ['reason' => $e->getMessage()]);

    return new Response(status: 400);
}

Детерминированные фикстуры в тестах

use CloudCastle\Clock\MockClock;
use CloudCastle\Uuid\UuidFactory;

$clock = MockClock::from('2026-01-01 00:00:00', 'UTC');
$factory = new UuidFactory(clock: $clock);

$order1 = $factory->uuid7();     // всегда одна и та же мс
$clock->advance(60.0);
$order2 = $factory->uuid7();     // ровно +1 минута

self::assertSame(60_000, $order2->timestampMs() - $order1->timestampMs());

Стабильные идентификаторы из внешних данных (v5)

use CloudCastle\Uuid\{Uuid, UuidNamespace};

// один и тот же URL всегда даёт один и тот же ID — дедупликация без БД
$pageId = Uuid::uuid5(UuidNamespace::Url, 'https://example.com/page?a=1');

// иерархия: приложение → пользователь → сессия
$appNs = Uuid::uuid5(UuidNamespace::Dns, 'my-app.example');
$userId = Uuid::uuid5($appNs, 'user:42');

Короткие коды приглашений (NanoID)

use CloudCastle\Uuid\NanoIdFactory;

$codes = new NanoIdFactory();

$invite = $codes->generateWithAlphabet('23456789ABCDEFGHJKLMNPQRSTUVWXYZ', 8);
// 'K7M2Q9RT' — без похожих символов (0/O, 1/I/L), удобно диктовать

Snowflake в шардированной системе

use CloudCastle\Uuid\SnowflakeFactory;

// каждый узел получает свою пару датацентр/воркер из конфигурации
$factory = new SnowflakeFactory(
    datacenterId: (int) getenv('DC_ID'),
    workerId: (int) getenv('WORKER_ID'),
);

$id = $factory->generate();
$shard = $id->workerId() % 4;        // маршрутизация по создателю

// разбор чужого идентификатора
$parsed = $factory->parse($requestId);
$parsed->dateTime();                  // когда создан

Импорт исторических данных (явный момент)

use CloudCastle\Uuid\UuidFactory;

$factory = new UuidFactory();

foreach ($legacyRows as $row) {
    $uuid = $factory->uuid7(new DateTimeImmutable($row['created_at']));
    // сортировка новых ключей совпадает с исторической хронологией
}

Миграция с ramsey/uuid и symfony/uid

// строки и байты совместимы в обе стороны
$ours = CloudCastle\Uuid\Uuid::fromString($ramseyUuid->toString());
$ramsey = Ramsey\Uuid\Uuid::fromBytes($ours->toBytes());

$oursFromSymfony = CloudCastle\Uuid\Uuid::fromBase58($symfonyUuid->toBase58());

Больше сценариев — в каталоге examples/ репозитория и на страницах возможностей.