README

Provider-agnostic UUID Value Object for PHP applications, designed as a base for domain-specific Entity IDs in DDD architectures.

Features

• Provider-agnostic - Works with ramsey/uuid or symfony/uid as backend
• RFC 9562 compliant - Full support for UUID versions 1-8, nil, and max
• Immutable Value Object - Safe for use in domain models
• Extensible - Easy to create domain-specific ID classes (UserId, OrderId, etc.)
• Testable - Accepts ClockInterface for deterministic testing
• Auto-detection - Automatically selects the best available provider

Installation

composer require php-architecture-kit/uuid

You also need at least one UUID provider:

# Option 1: Ramsey UUID (recommended for full RFC 9562 support)
composer require ramsey/uuid

# Option 2: Symfony UID
composer require symfony/uid

Quick Start

use PhpArchitecture\Uuid\Uuid;

// Generate a new UUID (defaults to v7)
$uuid = Uuid::new();

// Generate specific versions
$uuidV4 = Uuid::v4();                    // Random
$uuidV7 = Uuid::v7();                    // Time-ordered (recommended)
$uuidV1 = Uuid::v1();                    // Time-based (legacy)

// Deterministic UUIDs
$namespace = Uuid::fromString(Uuid::NAMESPACE_URL);
$uuidV5 = Uuid::v5($namespace, 'https://example.com');

// Parse existing UUID
$uuid = Uuid::fromString('df516cba-fb13-4f45-8335-00252f1b87e2');
$uuid = Uuid::fromBinary($binaryData);

// Use as Value Object
$uuid->value();       // 'df516cba-fb13-4f45-8335-00252f1b87e2'
$uuid->toString();    // 'df516cba-fb13-4f45-8335-00252f1b87e2'
$uuid->toBinary();    // 16 bytes
$uuid->getVersion();  // 4
$uuid->equals($other); // true/false

Creating Domain-Specific IDs

use PhpArchitecture\Uuid\Uuid;

final class UserId extends Uuid
{
    public static function new(): static
    {
        return static::v7(); // Time-ordered for better DB performance
    }
}

final class OrderId extends Uuid
{
    public static function new(): static
    {
        return static::v4(); // Random for privacy
    }
}

// Usage
$userId = UserId::new();
$orderId = OrderId::fromString('df516cba-fb13-4f45-8335-00252f1b87e2');

Provider Support Matrix

Performance

All benchmarks run on PHP 8.2, measuring mode (most frequent execution time).

Overhead Analysis

This library adds a thin abstraction layer over the underlying UUID providers. The table below shows the overhead compared to direct provider usage.

UUID Parsing (fromString)

UUID Parsing (fromBinary)

UUID Creation

Key Insights

1. Symfony backend is faster for most operations due to simpler implementation
2. Parsing without validation (fromString($uuid, false)) is ~3x faster than with validation
3. v4, v7, v8 have minimal overhead (~6-17%) - ideal for most use cases
4. v3, v5 with Ramsey have higher overhead due to namespace UUID parsing in each call
5. Autodetect mode selects the best provider automatically with minimal overhead
6. For hot paths, consider:
   • Using fromString($uuid, false) when UUID is already validated
   • Caching namespace UUIDs for v3/v5 operations
   • Using v4 or v7 for best performance

When Overhead Matters

API Reference

Factory Methods

Instance Methods

Namespace Constants

Uuid::NAMESPACE_DNS  // '6ba7b810-9dad-11d1-80b4-00c04fd430c8'
Uuid::NAMESPACE_URL  // '6ba7b811-9dad-11d1-80b4-00c04fd430c8'
Uuid::NAMESPACE_OID  // '6ba7b812-9dad-11d1-80b4-00c04fd430c8'
Uuid::NAMESPACE_X500 // '6ba7b814-9dad-11d1-80b4-00c04fd430c8'

Source of Truth

RFC 9562 - Universally Unique IDentifiers (UUIDs)

Testing

Package is tested with PHPUnit and PHPBench in the php-architecture-kit/workspace project.

License

MIT