Ramsey/UUID для PHP: полное руководство с примерами

1. Что это и зачем нужна

Библиотека Ramsey/UUID — это де-факто стандарт для работы с UUID (Universally Unique Identifier) в экосистеме PHP. UUID — это 128-битный идентификатор, который гарантирует уникальность без необходимости централизованного координатора. Библиотека предоставляет полный набор инструментов для генерации, парсинга, валидации и сериализации UUID всех стандартных версий (v1, v3, v4, v5, v6, v7, v8), а также поддержку нестандартных форматов.

Зачем это нужно? В современных распределённых системах, микросервисной архитектуре и базах данных (особенно NoSQL) UUID стали незаменимы. Они позволяют генерировать уникальные идентификаторы на клиенте или сервере без обращения к БД, что критически важно для офлайн-режимов, шардинга и репликации. Библиотека Ramsey/UUID решает проблему коллизий, обеспечивает детерминированную генерацию (v3/v5 на основе хешей) и поддерживает временные метки (v1/v6/v7), что полезно для сортировки по времени создания.

Библиотека полностью поддерживает PSR-4, PSR-11 (контейнеры), PSR-20 (Clock) и активно поддерживается сообществом. Она используется в таких крупных проектах, как Laravel, Symfony, Drupal и CakePHP.

2. Установка

Установка производится через Composer — стандартный менеджер пакетов для PHP. Выполните в корне вашего проекта:

composer require ramsey/uuid

Если вам нужна только поддержка UUID v4 (случайные), можно установить облегчённую версию без зависимостей от расширений:

composer require ramsey/uuid:^4.0

Для работы с UUID v1 (на основе времени) требуется расширение ext-uuid (PECL), но библиотека может использовать и чистый PHP-код. Рекомендуемая версия PHP — 8.0 или выше.

3. Быстрый старт — минимальный рабочий пример

Самый простой способ начать — сгенерировать UUID v4 (случайный). Создайте файл test.php:

<?php
require_once 'vendor/autoload.php';

use Ramsey\Uuid\Uuid;

// Генерация UUID v4
$uuid = Uuid::uuid4();
echo $uuid->toString(); // Вывод: 550e8400-e29b-41d4-a716-446655440000
?>

Запустите через консоль: php test.php. Вы получите уникальный идентификатор. Это всё, что нужно для базового использования.

4. Основные методы/функции/классы

Ниже приведены 8 ключевых методов библиотеки Ramsey/UUID. Каждый метод описан с сигнатурой, кратким описанием и рабочим примером.

4.1 `Uuid::uuid4()` — генерация случайного UUID (v4)

Сигнатура: public static function uuid4(): UuidInterface

Описание: Генерирует UUID версии 4 на основе криптографически стойкого генератора случайных чисел. Наиболее популярный вариант для большинства случаев.

<?php
use Ramsey\Uuid\Uuid;

$uuid = Uuid::uuid4();
echo $uuid->toString(); // Пример: 123e4567-e89b-12d3-a456-426614174000
?>

4.2 `Uuid::uuid1()` — генерация UUID на основе времени (v1)

Сигнатура: public static function uuid1(?string $node = null, ?int $clockSeq = null): UuidInterface

Описание: Генерирует UUID версии 1, который включает временную метку (100-наносекундные интервалы с 1582 года) и MAC-адрес узла. Полезен, когда нужно сортировать записи по времени создания.

<?php
use Ramsey\Uuid\Uuid;

// Простая генерация
$uuid1 = Uuid::uuid1();
echo $uuid1->toString(); // Пример: c232ab00-9414-11ec-b909-0242ac120002

// С указанием узла (MAC-адрес)
$uuid1Custom = Uuid::uuid1('00:11:22:33:44:55');
echo $uuid1Custom->toString();
?>

4.3 `Uuid::uuid3()` — детерминированный UUID на основе MD5 (v3)

Сигнатура: public static function uuid3(UuidInterface|string $ns, string $name): UuidInterface

Описание: Создаёт UUID версии 3 на основе хеша MD5 от имени и пространства имён. Для одного и того же набора входных данных всегда возвращает одинаковый UUID.

<?php
use Ramsey\Uuid\Uuid;
use Ramsey\Uuid\UuidInterface;

// Используем стандартное пространство имён DNS
$ns = Uuid::fromString('6ba7b810-9dad-11d1-80b4-00c04fd430c8'); // DNS namespace
$uuid3 = Uuid::uuid3($ns, 'example.com');
echo $uuid3->toString(); // Всегда один и тот же для example.com
?>

4.4 `Uuid::uuid5()` — детерминированный UUID на основе SHA-1 (v5)

Сигнатура: public static function uuid5(UuidInterface|string $ns, string $name): UuidInterface

Описание: Аналогичен v3, но использует SHA-1 вместо MD5. Рекомендуется использовать v5 вместо v3 из-за лучшей криптостойкости SHA-1.

<?php
use Ramsey\Uuid\Uuid;

$ns = Uuid::fromString('6ba7b811-9dad-11d1-80b4-00c04fd430c8'); // URL namespace
$uuid5 = Uuid::uuid5($ns, 'https://pythonlib.ru');
echo $uuid5->toString();
?>

4.5 `Uuid::uuid6()` — реорганизованный UUID на основе времени (v6)

Сигнатура: public static function uuid6(?UuidInterface $node = null, ?int $clockSeq = null): UuidInterface

Описание: UUID версии 6 — это реорганизованная версия v1, где временная метка идёт первой, что улучшает сортировку в базах данных (B-tree). Полезна для первичных ключей.

<?php
use Ramsey\Uuid\Uuid;

$uuid6 = Uuid::uuid6();
echo $uuid6->toString(); // Пример: 1ec9414c-232a-6b00-b909-0242ac120002
?>

4.6 `Uuid::uuid7()` — UUID на основе Unix timestamp (v7)

Сигнатура: public static function uuid7(?int $timestamp = null): UuidInterface

Описание: UUID версии 7 — современный стандарт (RFC 9562), основанный на Unix timestamp (миллисекунды) и случайных битах. Оптимален для баз данных, так как хорошо сортируется и не требует MAC-адреса.

<?php
use Ramsey\Uuid\Uuid;

// Текущее время
$uuid7 = Uuid::uuid7();
echo $uuid7->toString(); // Пример: 018f3a6b-7c8d-7b00-8000-000000000000

// С указанием конкретного timestamp (миллисекунды)
$customTime = 1710000000000; // 2024-03-09
$uuid7Custom = Uuid::uuid7($customTime);
echo $uuid7Custom->toString();
?>

4.7 `Uuid::fromString()` — парсинг UUID из строки

Сигнатура: public static function fromString(string $uuid): UuidInterface

Описание: Преобразует строковое представление UUID в объект UuidInterface. Выбрасывает InvalidArgumentException, если строка невалидна.

<?php
use Ramsey\Uuid\Uuid;

$uuidString = '550e8400-e29b-41d4-a716-446655440000';
$uuid = Uuid::fromString($uuidString);
echo $uuid->getVersion(); // 4
?>

4.8 `Uuid::isValid()` — проверка валидности UUID

Сигнатура: public static function isValid(string $uuid): bool

Описание: Статический метод для проверки, является ли строка корректным UUID (любой версии). Возвращает true или false.

<?php
use Ramsey\Uuid\Uuid;

$valid = '550e8400-e29b-41d4-a716-446655440000';
$invalid = 'not-a-uuid';

var_dump(Uuid::isValid($valid));   // bool(true)
var_dump(Uuid::isValid($invalid)); // bool(false)
?>

5. Реальный практический пример

Рассмотрим сценарий: создание REST API для управления заказами в интернет-магазине. Каждый заказ получает уникальный UUID v7 (для сортировки по времени), а товары внутри заказа — детерминированные UUID v5 на основе SKU. Также реализуем валидацию входящих UUID.

<?php
require_once 'vendor/autoload.php';

use Ramsey\Uuid\Uuid;
use Ramsey\Uuid\Exception\InvalidUuidStringException;

/**
 * Класс для работы с заказами
 */
class OrderService
{
    private string $namespace = '6ba7b811-9dad-11d1-80b4-00c04fd430c8'; // URL namespace

    /**
     * Создать новый заказ
     * @param array $items Массив SKU товаров
     * @return array Данные заказа
     */
    public function createOrder(array $items): array
    {
        // Генерируем UUID v7 для заказа (с временной меткой)
        $orderUuid = Uuid::uuid7();
        
        // Генерируем детерминированные UUID для каждого товара
        $itemUuids = [];
        foreach ($items as $sku) {
            // UUID v5 на основе SKU и пространства имён
            $itemUuid = Uuid::uuid5(Uuid::fromString($this->namespace), $sku);
            $itemUuids[] = $itemUuid->toString();
        }

        return [
            'order_id' => $orderUuid->toString(),
            'created_at' => $orderUuid->getDateTime()->format('Y-m-d H:i:s'),
            'items' => $itemUuids,
        ];
    }

    /**
     * Валидировать UUID из запроса
     * @param string $uuidString
     * @return bool
     */
    public function validateOrderId(string $uuidString): bool
    {
        try {
            $uuid = Uuid::fromString($uuidString);
            // Дополнительно проверяем версию (v7)
            return $uuid->getVersion() === 7;
        } catch (InvalidUuidStringException $e) {
            return false;
        }
    }

    /**
     * Получить информацию о UUID
     * @param string $uuidString
     * @return array
     */
    public function analyzeUuid(string $uuidString): array
    {
        try {
            $uuid = Uuid::fromString($uuidString);
            return [
                'valid' => true,
                'version' => $uuid->getVersion(),
                'variant' => $uuid->getVariant(),
                'time' => $uuid->getDateTime()?->format('Y-m-d H:i:s'),
                'node' => $uuid->getNode(),
            ];
        } catch (InvalidUuidStringException $e) {
            return ['valid' => false, 'error' => $e->getMessage()];
        }
    }
}

// Пример использования
$service = new OrderService();

// Создаём заказ
$order = $service->createOrder(['SKU-001', 'SKU-002', 'SKU-003']);
echo "Создан заказ:\n";
print_r($order);

// Валидируем UUID
$testUuid = $order['order_id'];
echo "\nВалидация UUID {$testUuid}: ";
echo $service->validateOrderId($testUuid) ? 'OK' : 'FAIL';

// Анализируем UUID
echo "\n\nАнализ UUID:\n";
print_r($service->analyzeUuid($testUuid));

// Проверка невалидного UUID
echo "\nАнализ невалидного UUID:\n";
print_r($service->analyzeUuid('not-a-uuid'));
?>

Этот пример показывает, как использовать разные версии UUID в одном приложении: v7 для временных меток, v5 для детерминированных идентификаторов, и методы валидации/анализа.