DOCSEARCHbyAlgolia
Submit Docs

ramsey/uuid

repository·4.x·Indexed 11 days ago

https://github.com/ramsey/uuid

A PHP library for generating and working with Universally Unique Identifiers (UUIDs) in accordance with RFC 4122. It supports customization via dependency injection of builders, codecs, and calculators, and provides a migration path from version 3 to 4.

Tokens
30.8K
Snippets
95
Records
177
Agent score
94%

What's inside ramsey/uuid

  1. Overview of ramsey/uuid capabilities

    4.x
    ramsey/uuid is a PHP library designed for generating and manipulating Universally Unique Identifiers (UUIDs). It provides full support for the RFC 9562 (formerly RFC 4122) standards, covering versions 1, 2, 3, 4, 5, 6, 7, and 8. Additionally, the library supports non-standard features like GUIDs and various methods for encoding and decoding UUIDs.

  2. Customize ramsey/uuid via dependency injection

    4.x

    ramsey/uuid allows you to modify its standard behavior by replacing core components through dependency injection. You can replace almost any builder, codec, converter, generator, provider, and more.

    To perform customization, you can use:

    • FeatureSet
    • UuidFactory
    • Uuid::setFactory() to replace the global, static factory used by the static methods on the Uuid class.

  3. Handle changes to Uuid static method return types

    4.x

    In version 4, static methods on the Uuid class return more specific types that implement Rfc4122\UuidInterface (which in turn implements UuidInterface).

    If your code uses UuidInterface as a type hint, no changes are required.

    However, if you type-hint specifically for the Uuid class, you may need to update your code. The following mapping applies:

    Method3.x Returned4.x Returns
    Uuid::uuid1()UuidRfc4122\UuidV1
    Uuid::uuid3()UuidRfc4122\UuidV3
    Uuid::uuid4()UuidRfc4122\UuidV4
    Uuid::uuid5()UuidRfc4122\UuidV5

    Additionally, Uuid::fromString(), Uuid::fromBytes(), and Uuid::fromInteger() now return specific instances based on the input (e.g., a version 1 UUID returns an Rfc4122\UuidV1). If the input is a valid 128-bit number but not a valid RFC 4122 UUID, it returns Nonstandard\Uuid.

  4. Understand the limitations of Version 2 UUIDs

    4.x

    Version 2 UUIDs have several significant trade-offs:

    Privacy

    Unless using a randomly-generated node, Version 2 UUIDs expose the machine's MAC address and local identifiers (like account or group IDs). This can be used to identify a specific user on a specific machine at a specific time.

    Limited Uniqueness

    Because the local identifier replaces the lower 32 bits of the timestamp and the domain replaces the lower 8 bits of the clock sequence, the clock only advances approximately every 7 minutes.

    • Constraint: Only 64 unique UUIDs per combination of node, domain, and identifier can be generated per 7-minute tick.
    • Mitigation: Using a random node increases uniqueness to $2^{53}$ per tick, but you lose local uniqueness.

    Lossy Timestamps

    When calling UuidV2::getDateTime(), the 32 lower bits of the timestamp (which contain the local identifier) are replaced with zeros. This results in a loss of precision. The reconstructed timestamp is an approximation and can be off by up to ~7 minutes (429.49 seconds).

  5. Use NumberInterface for numeric values

    4.x

    The NumberInterface extends TypeInterface and is used for values that represent numbers. It provides a consistent way to check if a numeric value is negative.

    // Example of checking sign on a NumberInterface implementation
if ($number->isNegative()) {
    // handle negative value
}

  6. Use UUID interfaces for type hinting

    4.x

    When using type hints in your code, it is best practice to use interfaces rather than specific implementation classes.

    • Ramsey\Uuid\UuidInterface: The most lenient interface.
    • Ramsey\Uuid\Rfc4122\UuidInterface: Ensures the UUID conforms to the RFC 9562 (formerly RFC 4122) standard. This is the recommended starting point if you need standard-compliant UUIDs.

  9. Migrate from Uuid class to concrete UUID classes

    4.x

    The Ramsey\Uuid\Uuid class is being transitioned. In version 5, its constructor will be private and the class will be final. While the class remains for common constants and static methods, you should migrate to more specific concrete classes for instantiation.

    Recommended concrete classes:

    • Ramsey\Uuid\Rfc4122\UuidV1
    • Ramsey\Uuid\Rfc4122\UuidV3
    • Ramsey\Uuid\Rfc4122\UuidV4
    • Ramsey\Uuid\Rfc4122\UuidV5
    • Ramsey\Uuid\Nonstandard\Uuid

  10. Choosing a UUID version (RFC 9562 / RFC 4122)

    4.x
    The ramsey/uuid library implements eight different versions of UUIDs as defined by RFC 9562 (formerly RFC 4122). Each version uses a different generation algorithm and serves different use cases. When deciding which version to use, consider whether you need determinism (name-based), time-based sorting (monotonically increasing), or randomness.

  11. Understand the difference between GUID and UUID byte orders

    4.x

    It is critical to know whether your bytes are stored as a GUID or a UUID before decoding, as decoding them with the wrong logic will result in incorrect values.

    • RFC 9562 (UUID) Byte Order: Uses big-endian (network byte order). The bytes are stored in the same order they appear in the string representation.
    • Microsoft GUID Byte Order: Uses little-endian for the first 64 bits (the beginning four-byte group and the next two two-byte groups are reversed) and big-endian for the remaining 64 bits.

    Note: You can always create both a GUID and a UUID from the same string value, but their underlying byte arrays will be different.

  12. Implement and use a custom validator

    4.x
    If you need custom validation logic, create a class that implements the Ramsey\Uuid\Validator\ValidatorInterface. Once implemented, you can register your custom validator by passing an instance of your class to setValidator() on a UuidFactory, and then applying that factory to the Uuid class via setFactory().