ramsey/uuid

ramsey/uuid is the de facto standard PHP library for generating and working with universally unique identifiers. It implements every UUID version defined in RFC 4122 (time-based, name-based, random, and version 6/7/8 variants) plus several non-standard GUID formats used by other systems such as Microsoft’s COM.

Beyond generation, the library provides validation, comparison, and codec support for converting UUIDs between string, binary, and numeric representations, along with a pluggable FeatureSet/provider architecture that lets consumers swap in custom random-number, time, or node providers — useful for testing or specialized environments.

What You Get

• Generation of UUID versions 1 through 8 as defined by RFC 4122, including the newer time-ordered v6/v7
• Support for non-standard GUID formats (e.g. Microsoft COM-style GUIDs) via the Guid/Nonstandard namespaces
• Validation and comparison utilities for checking and comparing UUID values
• Codec support for converting UUIDs between string, binary, and big-integer numeric representations
• A pluggable FeatureSet/provider architecture for swapping random-number, time, and node providers

Common Use Cases

• Generating primary keys or public-facing identifiers for database records instead of sequential integers
• Validating UUID-formatted input in API request handlers
• Generating deterministic, name-based UUIDs (v3/v5) for reproducible identifiers derived from a namespace and name
• Interoperating with Microsoft COM-style GUIDs in legacy or cross-platform integrations

Under The Hood

Architecture - The library centers on Uuid.php/UuidFactory.php, which delegate actual generation logic to a Generator/ namespace (separate generators per UUID version/strategy) and represent field data through Fields/ and Rfc4122/ for RFC-compliant UUIDs versus Guid//Nonstandard/ for non-standard variants. Codec/ and Converter/ handle serialization between string, binary, and numeric formats, while Builder/ assembles the correct concrete UUID class based on the requested version, and Validator/ centralizes format-checking logic used across the library.

Tech Stack - The library depends on brick/math for arbitrary-precision integer arithmetic (needed to correctly represent 128-bit UUID values without precision loss) and the sibling ramsey/collection package for typed collection support, requiring PHP 8.0+. Its FeatureSet abstraction lets alternate randomness/time/node sources be injected, which is also how the library adapts its behavior across different PHP runtime capabilities.

Code Quality - With 114 source files organized into narrowly scoped namespaces (Builder, Codec, Converter, Generator, Validator, Provider), responsibilities are cleanly separated by concern rather than by UUID version alone. The project enforces strict tooling in CI — PHPStan (including dedicated Mockery and PHPUnit extensions), phpcs via captainhook git hooks, and phpbench for performance benchmarking — reflecting a mature, quality-gated release process for a library used as a foundational dependency across the PHP ecosystem.

API Design - The primary entry points (Uuid::uuid4(), Uuid::uuid7(), Uuid::fromString()) are short, version-specific static factory methods that map directly onto RFC 4122’s version numbers, making the common case a one-line call. The DeprecatedUuidMethodsTrait and DeprecatedUuidInterface show a deliberate, documented migration path as the API has evolved, minimizing breakage for long-time consumers while still improving the interface over time.