PHPackages                             php-architecture-kit/uuid - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. php-architecture-kit/uuid

ActiveLibrary[Utility & Helpers](/categories/utility)

php-architecture-kit/uuid
=========================

UUID Value Object with provider-agnostic facade and optional interoperability with popular UUID libraries.

1.1.0(1mo ago)193MITPHPPHP ^7.4 || ^8.0

Since Feb 11Pushed 1mo agoCompare

[ Source](https://github.com/php-architecture-kit/uuid)[ Packagist](https://packagist.org/packages/php-architecture-kit/uuid)[ Docs](https://github.com/php-architecture-kit/uuid)[ RSS](/packages/php-architecture-kit-uuid/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (2)Versions (4)Used By (3)

php-architecture-kit/uuid
=========================

[](#php-architecture-kituuid)

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

Features
--------

[](#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
------------

[](#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
-----------

[](#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
----------------------------

[](#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
-----------------------

[](#provider-support-matrix)

FeatureRamseySymfonyNotesUUID v1✅✅Time-basedUUID v1 + clockSequence✅❌Ramsey onlyUUID v3✅✅MD5 hashUUID v4✅✅RandomUUID v5✅✅SHA-1 hashUUID v6✅✅Time-ordered (improved v1)UUID v6 + clockSequence✅❌Ramsey onlyUUID v7✅✅Time-ordered + randomUUID v8✅❌Custom dataValidation✅✅Performance
-----------

[](#performance)

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

### Overhead Analysis

[](#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-fromstring)

OperationDirect RamseyThis LibraryOverheadWith validation1.23μs2.27μs+1.04μs (+85%)Without validationN/A0.82μs—OperationDirect SymfonyThis LibraryOverheadWith validation2.87μs2.68μs-0.19μs (-7%)Without validationN/A0.85μs—#### UUID Parsing (`fromBinary`)

[](#uuid-parsing-frombinary)

OperationDirect RamseyThis LibraryOverheadWith validation2.44μs4.97μs+2.53μs (+104%)Without validationN/A2.36μs—OperationDirect SymfonyThis LibraryOverheadWith validation3.79μs5.20μs+1.41μs (+37%)Without validationN/A2.33μs—#### UUID Creation

[](#uuid-creation)

VersionDirect RamseyThis LibraryOverheadv121.58μs24.34μs+2.76μs (+13%)v38.46μs24.90μs+16.44μs (+194%)v45.15μs6.02μs+0.87μs (+17%)v57.67μs26.56μs+18.89μs (+246%)v622.03μs28.14μs+6.11μs (+28%)v77.86μs9.15μs+1.29μs (+16%)v85.07μs5.36μs+0.29μs (+6%)VersionDirect SymfonyThis LibraryOverheadv15.27μs11.19μs+5.92μs (+112%)v36.17μs6.25μs+0.08μs (+1%)v41.81μs3.04μs+1.23μs (+68%)v56.26μs9.09μs+2.83μs (+45%)v66.93μs12.30μs+5.37μs (+77%)v73.81μs4.65μs+0.84μs (+22%)### Key Insights

[](#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

[](#when-overhead-matters)

Use CaseTypical VolumeImpactHTTP Request ID1/requestNegligibleEntity IDs10-100/requestNegligibleBatch processing10,000+/batch~10-60ms extraReal-time systemsμs-sensitiveConsider direct providerAPI Reference
-------------

[](#api-reference)

### Factory Methods

[](#factory-methods)

MethodDescription`Uuid::new()`Creates new UUID (defaults to v7)`Uuid::fromString(string $uuid, bool $validate = true)`Parse UUID string`Uuid::fromBinary(string $bytes, bool $validate = true)`Parse 16-byte binary`Uuid::v1(?ClockInterface $clock, ?int $clockSequence, ?string $nodeIdentifier)`Time-based`Uuid::v3(Uuid $namespace, string $name)`MD5 hash-based`Uuid::v4()`Random`Uuid::v5(Uuid $namespace, string $name)`SHA-1 hash-based`Uuid::v6(?ClockInterface $clock, ?int $clockSequence, ?string $nodeIdentifier)`Time-ordered`Uuid::v7(?ClockInterface $clock)`Unix timestamp + random`Uuid::v8(string $customData)`Custom 16-byte data`Uuid::nil()`Nil UUID (all zeros)`Uuid::max()`Max UUID (all ones)### Instance Methods

[](#instance-methods)

MethodDescription`value(): string`Get UUID string`toString(): string`Get UUID string`toBinary(): string`Get 16-byte binary`getVersion(): int`Get UUID version (0-15)`getTime(): ?DateTimeImmutable`Get timestamp (v1/v6/v7)`getClockSequence(): ?int`Get clock sequence (v1/v6)`getNode(): ?string`Get node identifier (v1/v6)`equals(self|string $other): bool`Compare UUIDs`validate(): bool`Validate UUID format### Namespace Constants

[](#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
---------------

[](#source-of-truth)

[RFC 9562 - Universally Unique IDentifiers (UUIDs)](https://www.rfc-editor.org/rfc/rfc9562.html)

Testing
-------

[](#testing)

Package is tested with PHPUnit and PHPBench in the [php-architecture-kit/workspace](https://github.com/php-architecture-kit/workspace) project.

License
-------

[](#license)

MIT

###  Health Score

38

—

LowBetter than 83% of packages

Maintenance89

Actively maintained with recent releases

Popularity6

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity42

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~43 days

Total

3

Last Release

55d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/145db325ca53baabce2d955faebe43d56bc4f3122b9ae463d41ee0e5da487cea?d=identicon)[patrykbaszak](/maintainers/patrykbaszak)

---

Top Contributors

[![patrykbaszak](https://avatars.githubusercontent.com/u/66377724?v=4)](https://github.com/patrykbaszak "patrykbaszak (11 commits)")

---

Tags

uuididentifierdddframework agnostic

### Embed Badge

![Health badge](/badges/php-architecture-kit-uuid/health.svg)

```
[![Health](https://phpackages.com/badges/php-architecture-kit-uuid/health.svg)](https://phpackages.com/packages/php-architecture-kit-uuid)
```

###  Alternatives

[ramsey/uuid

A PHP library for generating and working with universally unique identifiers (UUIDs).

12.6k745.0M4.0k](/packages/ramsey-uuid)[ecotone/ecotone

Enterprise architecture layer for Laravel and Symfony — CQRS, Event Sourcing, Durable Workflows (Sagas, Orchestrators), Projections, and Outbox messaging via PHP attributes.

564576.7k52](/packages/ecotone-ecotone)[pascaldevink/shortuuid

PHP 7.4+ library that generates concise, unambiguous, URL-safe UUIDs

5941.9M16](/packages/pascaldevink-shortuuid)[flow-php/etl

PHP ETL - Extract Transform Load - Abstraction

378604.0k104](/packages/flow-php-etl)[keiko/uuid-shortener

A simple shortener library for RFC 4122 compatible UUIDs. Change your 36 chars long UUID into it's shorter equivalent.

150227.4k3](/packages/keiko-uuid-shortener)[oittaa/uuid

A small PHP class for generating RFC 9562 universally unique identifiers (UUID) from version 3 to version 8.

54324.8k6](/packages/oittaa-uuid)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)