ramsey/uuid

This system is a PHP library for generating, parsing, and manipulating UUIDs and GUIDs, supporting versions 1 through 8 as well as Microsoft GUIDs and nonstandard variants. It provides specialized capabilities for database-optimized storage via COMB UUIDs, deterministic generation using fixed time or node providers, and arbitrary-precision arithmetic for large numeric conversions. The library ensures strict standards compliance with RFC 9562 while offering performance optimizations through lazy instantiation and type-safe value objects.

17 changes.

The project underwent a major restructuring for version 4.x, renaming the library to ramsey/uuid and enforcing modern PHP standards. This period introduced support for UUID version 7 and refactored core components like codecs, builders, and providers to improve performance and type safety.

25 changes.

The project restructured its core UUID implementation to align with the updated RFC 9562 standard, introducing dedicated classes for all UUID versions including V7 and V8. This period also focused on enhancing type safety through new value objects and arbitrary-precision math support, while significantly expanding test coverage and adding features like Microsoft GUID support and lazy loading for performance optimization.

The library now includes dedicated classes to handle Microsoft GUIDs, which use a different byte-ordering scheme (little-endian for the first three fields) compared to standard RFC 4122 UUIDs. This change introduces \Guid\, \Fields\, and \GuidBuilder\ classes in the \Ramsey\\Uuid\\Guid\ namespace, allowing users to create, parse, and inspect GUIDs with correct field extraction (such as \getTimeLow\, \getTimeMid\, and \getTimeHiAndVersion\) and variant/version validation specific to the Microsoft format.

src/Guid · high confidence

The library now includes classes in the \Ramsey\\Uuid\\Nonstandard\ namespace to handle UUIDs that do not conform to the RFC 9562 standard. This introduces \Nonstandard\\Uuid\ and \Nonstandard\\Fields\ to represent and parse these nonstandard variants, along with a \Nonstandard\\UuidBuilder\ to construct them. Additionally, a \Nonstandard\\UuidV6\ class is added to support version 6 (reordered time) UUIDs, but it is marked as deprecated in favor of the standard \Rfc4122\\UuidV6\ implementation.

src/Nonstandard · high confidence

A new SystemDceSecurityProvider class has been introduced to support the generation of version 2 (DCE Security) UUIDs. This provider retrieves the operating system's user ID (UID) and group ID (GID) by executing system commands (such as \id -u\ on Unix-like systems and \whoami\/\net user\ on Windows) to populate the DCE Security portion of the UUID. This enables users to generate UUIDs that include the local user and group identifiers, a capability previously unavailable in this library.

src/Provider/Dce · high confidence

Developers can now run the test suite in isolated virtual machines using Vagrant for Linux (Ubuntu), FreeBSD, and Windows. This change adds Vagrantfiles and platform-specific README instructions to the resources/vagrant directory, allowing users to spin up pre-configured environments with the necessary PHP extensions and tools to execute tests locally.

resources · high confidence

The library now provides a \ValidatorInterface\ and a \GenericValidator\ implementation to validate whether strings represent valid UUIDs. The \GenericValidator\ checks strings against a standard UUID pattern, stripping common prefixes and delimiters, and can be used to verify UUID format before processing.

src/Validator · high confidence

A new \LazyUuidFromString\ class has been added to the \Ramsey\\Uuid\\Lazy\ namespace to optimize UUID instantiation, serialization, and string conversion. This internal implementation allows UUIDs to be created and serialized without immediately parsing their internal fields, deferring the more expensive parsing work until specific methods (like \getDateTime\ or \getFieldsHex\) are actually called. This change improves performance for common operations while maintaining full compatibility with the existing \UuidInterface\.

src/Lazy · high confidence

The Generator namespace now includes new classes to support additional UUID standards and patterns. CombGenerator creates combined UUID/timestamp identifiers (COMBs) for improved database indexing, while DceSecurityGenerator enables the creation of Version 2 (DCE Security) UUIDs. Additionally, UnixTimeGenerator implements Version 7 (Unix Epoch Time) UUIDs, providing monotonic, sortable identifiers based on millisecond timestamps. The update also introduces NameGeneratorInterface and its implementations (DefaultNameGenerator, PeclUuidNameGenerator) to standardize how Version 3 and 5 UUIDs are generated from namespace and name inputs.

src/Generator · high confidence

The library introduces two new interfaces in the Ramsey\\Uuid\\Converter namespace: NumberConverterInterface and TimeConverterInterface. NumberConverterInterface defines methods to convert between hexadecimal strings and numeric string representations of integers, supporting values larger than PHP\_INT\_MAX. TimeConverterInterface provides methods to calculate UUID timestamps from seconds and microseconds (returning a Hexadecimal value) and to convert UUID timestamps back to Unix time (returning a Time object). These interfaces standardize the contract for UUID conversion logic.

src/Converter · high confidence

The library now includes dedicated classes for time source abstraction within the Ramsey\\Uuid\\Provider\\Time namespace. FixedTimeProvider allows users to supply a known or previously generated time for deterministic UUID generation, while SystemTimeProvider retrieves the current time using PHP's built-in gettimeofday function. Both classes implement the TimeProviderInterface, enabling consistent time-based UUID generation strategies.

src/Provider/Time · high confidence

The library introduces dedicated value objects in the \Ramsey\\Uuid\\Type\ namespace to provide type safety for data previously returned as plain strings. \Hexadecimal\ ensures hexadecimal strings are valid and non-empty, while \Integer\, \Decimal\, and \Time\ enforce that numeric values and timestamps are strictly typed, supporting large integers beyond PHP's native limits by storing them as strings. These classes implement \TypeInterface\ (which extends \JsonSerializable\ and \Serializable\) and \NumberInterface\ (adding \isNegative()\), ensuring consistent serialization and immutability for UUID components.

src/Type · high confidence

The Rhumsaa\\Uuid library has been removed from the project. This eliminates the ability to generate, parse, and manipulate UUIDs using the previous Rhumsaa implementation, requiring users to adopt an alternative UUID solution.

library · high confidence

The build process now explicitly excludes build artifacts, caches, and logs from version control. A new .gitignore file in the build directory ignores all contents except for the .gitignore file itself and the cache and logs directories (which are preserved via .gitkeep files). This ensures that generated build outputs and runtime logs are not committed to the repository, keeping the source tree clean.

build · high confidence

The library introduces GenericNumberConverter as the new standard for converting decimal numbers to and from hexadecimal values, utilizing the provided CalculatorInterface. Consequently, BigNumberConverter and DegradedNumberConverter are deprecated; BigNumberConverter now acts as a thin wrapper around GenericNumberConverter, and DegradedNumberConverter is no longer necessary for 32-bit systems. Users should transition to GenericNumberConverter for number conversion logic.

src/Converter/Number · high confidence

The library now encourages using the new \getFields()\ method to access UUID components, deprecating the previous individual hex getters (such as \getTimeLowHex()\, \getNodeHex()\, and \getClockSequenceHex()\) which are now consolidated in the \DeprecatedUuidInterface\ and \DeprecatedUuidMethodsTrait\. Additionally, the library adds support for generating Version 7 (Unix Epoch time) UUIDs, exposing this capability through new \Uuid::uuid7()\ factory methods, the \v7()\ global function, and a dedicated \UnixTimeGenerator\ within the \FeatureSet\.

src · high confidence

The library now provides a new \FieldsInterface\ and a \SerializableFieldsTrait\ in the \src/Fields\ namespace to standardize how UUID fields are serialized. This change introduces a structured way to handle the byte representation of UUID fields, implementing PHP's \Serializable\ interface and the newer \\_\serialize\/\\\unserialize\ methods. Users relying on the internal structure of UUID fields may see changes in how these components are serialized, particularly with the introduction of base64 decoding fallbacks in \unserialize\ and strict validation in \\\_unserialize\.

src/Fields · high confidence

The library now provides a structured set of specific exception classes under the \Ramsey\\Uuid\\Exception\ namespace, replacing the previous generic runtime exceptions. This change introduces a common \UuidExceptionInterface\ and concrete classes such as \DateTimeException\, \DceSecurityException\, \InvalidArgumentException\, \InvalidBytesException\, \InvalidUuidStringException\, \NameException\, \NodeException\, \RandomSourceException\, \TimeSourceException\, \UnableToBuildUuidException\, and \UnsupportedOperationException\. Additionally, the legacy \UnsupportedOperationException\ has been renamed to \BuilderNotFoundException\ and moved to this new namespace. Users can now catch specific error conditions (e.g., invalid UUID strings or random source failures) rather than relying on broad exception types.

src/Exception · high confidence

The library now includes a new \BrickMathCalculator\ implementation in \src/Math\ that leverages the \brick/math\ library for arbitrary-precision arithmetic. This change introduces a \CalculatorInterface\ and a \RoundingMode\ class to standardize mathematical operations, along with a \BrickMathRoundingMode\ polyfill to ensure compatibility with both older (UPPER\_SNAKE\_CASE) and newer (PascalCase) constant naming conventions in \brick/math\. Users can now rely on this calculator for precise addition, subtraction, multiplication, division, and base conversions, replacing previous less precise or different calculation methods.

src/Math · high confidence

The \src/Rfc4122\ directory has been completely restructured to align with the updated RFC 9562 standard. This change introduces dedicated concrete classes for every UUID version (V1 through V8), including new support for Version 2 (DCE Security), Version 6 (Reordered Time), Version 7 (Unix Epoch Time), and Version 8 (Custom Format). It also adds specific classes for special UUIDs: \NilUuid\ (all zeros) and \MaxUuid\ (all ones). The internal field handling is now encapsulated in a new \Fields\ class and \FieldsInterface\, which provide access to specific components like timestamps and clock sequences. The \UuidBuilder\ has been updated to route byte strings to these new specific version classes, and a new \Validator\ ensures strict compliance with the RFC 9562 variant pattern.

src/Rfc4122 · high confidence

The UUID builder system has been restructured to support specific UUID versions and types, introducing new concrete builders such as Rfc4122UuidBuilder, GuidBuilder, and NonstandardUuidBuilder, along with a FallbackBuilder that iterates through available builders to construct a UUID. The UuidBuilderInterface now accepts raw bytes instead of fields, and the previously generic DefaultUuidBuilder is deprecated in favor of the specific Rfc4122UuidBuilder. Additionally, the DegradedUuidBuilder is deprecated as 32-bit support is no longer necessary, and the BuilderCollection class is deprecated in favor of generic iterable types for better type safety.

src/Builder · high confidence

The codec layer has been restructured to improve performance and clarity. A new CodecInterface defines the core encoding/decoding contract, implemented by a refactored StringCodec that now handles standard UUID string and binary conversions. New specialized codecs have been added: OrderedTimeCodec for optimizing version 1 UUID storage in databases by rearranging timestamp bytes, GuidStringCodec for handling GUID-specific byte ordering, and TimestampFirstCombCodec for generating COMB UUIDs with timestamps in the first 48 bits. TimestampLastCombCodec is also introduced for consistency with COMB generation patterns. These changes optimize byte manipulation and provide clearer separation of concerns for different UUID formats.

src/Codec · high confidence

The node provider implementation has been restructured to improve reliability and standards compliance. A new FallbackNodeProvider allows chaining multiple providers, automatically trying the next one if the current fails. The RandomNodeProvider now strictly follows RFC 9562 by setting the multicast bit in generated random nodes. The SystemNodeProvider has been hardened with better error handling, including checks for disabled functions and readable paths, and now supports FreeBSD systems. Additionally, a StaticNodeProvider was added to allow users to provide a fixed node value, and the NodeProviderCollection class is now deprecated in favor of generic iterables.

src/Provider/Node · high confidence

The provider layer has been reorganized under the new Ramsey\\Uuid\\Provider namespace, introducing specific interfaces for time, node, and DCE security operations. TimeProviderInterface now defines getTime() (replacing the deprecated currentTime()), NodeProviderInterface::getNode() returns a Hexadecimal type, and a new DceSecurityProviderInterface supports version 2 (DCE Security) UUIDs by providing getUid() and getGid() methods. These changes also include stricter type hints and return types across the interfaces.

src/Provider · high confidence

The time conversion logic in the Converter/Time namespace has been restructured to improve reliability and performance. A new GenericTimeConverter now serves as the primary implementation for standard UUID time conversions, replacing the previous BigNumberTimeConverter which is now deprecated and acts as a thin wrapper. A new PhpTimeConverter has been added to utilize native PHP integer operations for speed, with a fallback to the Generic converter for large values that might overflow. Additionally, a DegradedTimeConverter is deprecated as it is no longer necessary, and a new UnixTimeConverter has been introduced to support UUID version 7 (Unix Epoch time) by converting milliseconds since the Unix epoch.

src/Converter/Time · high confidence

The project has been reorganized to align with the 4.x release, including renaming the library from Rhumsaa\\Uuid to ramsey/uuid and updating the namespace to Ramsey. The repository now enforces PSR-12 coding standards via a new phpcs.xml.dist configuration and uses CaptainHook to automate pre-commit linting and testing. Documentation and security policies have been updated, with a new SECURITY.md file and a Code of Conduct based on the Contributor Covenant. The PHPUnit configuration has been migrated from phpunit.dist.xml to phpunit.xml.dist, and the .gitattributes file now excludes development and test files from exported packages.

(repo-wide) · high confidence

Added benchmark suite for UUID generation, conversion, and serialization; Added static analysis fixtures to verify UUID API purity and non-empty string contracts; Added test coverage for UUID generator components; Added test coverage for node providers; Added test coverage for time converter implementations; Added tests for BigNumberConverter and GenericNumberConverter; Added tests for Decimal, Hexadecimal, Integer, and Time types; Added tests for GenericValidator; Added tests for RFC 4122 UUID fields and version-specific builders; Added tests for SystemDceSecurityProvider; Added tests for the BrickMathCalculator and rounding mode resolution; Added unit tests for FixedTimeProvider and SystemTimeProvider; Added unit tests for GuidStringCodec, OrderedTimeCodec, and StringCodec; Added unit tests for TimestampFirstComb and TimestampLastComb codecs; Added unit tests for UUID builders; Expanded test coverage for UUID generation, parsing, and utility functions; Removed legacy UuidTest.php file.

The library has been updated to require PHP 8.0 or higher and now depends on brick/math (supporting versions 0.8.16 through 1.0) for arbitrary-precision arithmetic, replacing previous math implementations. The package name has changed from Rhumsaa/Uuid to ramsey/uuid, with a composer replace directive ensuring backward compatibility for existing installations. Development tooling has been modernized with updated versions of PHPUnit, PHPStan, and Mockery, and the codebase has migrated to PSR-4 autoloading under the Ramsey\\Uuid namespace.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 48 → 73 (+25.2)
• Rubric changed (rubric-2026.08.15 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 100 → 97 (-2.6)
• Architecture 96 → 100 (+4.4)
• Maturity 54 → 60 (+6.2)
• Readiness 32 → 90 (+58.0)
• Security 51 → 76 (+25.6)

• Coverage not measured — test suite did not build
• Dimension evaluation failed
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• …and 4 more

• Documentation: contradicts the code (docs/upgrading/3-to-4.rst)
• Documentation: no installation or build instructions (README.md)
• Dual entry points for string parsing with different internal behaviors. Uuid::fromString is the primary factory method, but LazyUuidFromString is a concrete class that can be instantiated directly with a string. This creates ambiguity: should users call the static factory or instantiate the lazy wrapper? The lazy wrapper also exposes fromBytes as a static method, while the main Uuid class uses instance methods for conversion (fromBytes, fromString), creating an inconsistency in static vs instance usage patterns for similar operations.
• Duplicated block (12 lines × 2) (src/DeprecatedUuidMethodsTrait.php)
• Duplicated block (6 lines × 2) (src/Guid/Fields.php)
• Duplicated block (6 lines × 6) (src/Fields/SerializableFieldsTrait.php)
• Duplicated block (7 lines × 2) (src/Guid/GuidBuilder.php)
• Duplicated block (7 lines × 7) (src/Nonstandard/UuidV6.php)
• Duplicated block (9 lines × 2) (src/Codec/GuidStringCodec.php)
• Duplicated block (9 lines × 2) (src/Guid/Fields.php)
• Duplicated block (9 lines × 2) (src/Nonstandard/UuidV6.php)
• High CVE: [GHSA redacted] (composer.lock)
• High CVE: [GHSA redacted] (composer.lock)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• …and 40 more

• 3 commits — 1 feature/other, 2 fixes

• (root) — 2 commits
• .github/workflows — 1 commit

• fix: Fix: Add support for brick/math:^0.19, brick/math:^0.20, and brick/math:^1.0 (#642)
• fix: Fix: Downgrade brick/math for locked dependencies on PHP 8.0 and 8.1 only (#646)
• change: Prepare release 4.9.4

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

ramsey/uuid was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.