Download the PHP package boondoc/uuid without Composer

Boondoc/uuid

Boondoc/uuid is a PHP5.6+ class for handling and generating RFC 4122 versions 1, 3, 4 and 5 (variant 1) Universally Unique Identifiers (UUIDs).

Three string output formats are provided:

• “Long” format is a standard 36-character string (lower case, segmented with dashes, no enclosing braces)
• “Short” format is a 22-character base64-encoded string using URL-safe characters and no padding
• “Binary” format is a 16-character octet blob (big-endian encoding)

UUID variants 0, 3 and 5 are not generated, or accepted as valid input.

Once generated, UUIDs are stored and treated as strings, with no internal structure — timestamp, clock sequence, etc. are ignored. Analysis and rearrangement of component fields for sorting is not supported.

Installation

With Composer:

Manual Installation:

Download the file uuid.php and include it in your code with a require statement.

Usage

Import the class:

A uuid object is assigned its value at creation. Once created, the objectʼs value cannot be altered, although it can be retrieved in multiple formats.

Import value:

Passing a valid UUID as the $uuid parameter will attempt to assign that value to the new uuid object.

Note that another uuid object instance is considered a valid UUID for this purpose:

Generate random value:

Passing no arguments will result in a new version 4 UUID being generated and assigned to the new uuid object.

Generate namespaced value:

If the $uuid parameter is not empty, but is not a valid UUID, a new version 5 UUID will be generated using the $uuid parameter as its “name” input, and assigned to the new uuid object.

If the $namespace parameter is a valid UUID, it will be used as the “namespace” argument of the version 5 generation.

If the $namespace parameter is omitted, or is boolean true, then a default “namespace” argument is used instead. At the start of script execution, the default namespace is initialised to the “nil” UUID, but it can be subsequently set to any valid UUID.

Suppressing namespaced generation:

If the $namespace parameter is boolean false, then namespaced generation is suppressed.

In this case, an empty $uuid parameter still results in generation of a version 4 UUID.

Otherwise, the $uuid parameter is treated strictly as a value to be imported. In the event that $uuid is not empty, but also not a valid UUID, and $namespace is boolean false, either an InvalidString or an InvalidBinary exception is thrown (see below).

Factory notation:

An alternate, factory-style notation is also available:

Factory-style notation also allows access to version 1 and 3 UUIDs; these are not available through direct object instantiation.

Since version 1 UUIDs rely on a MAC address, and PHP has no reliable, platform-agnostic method of obtaining the MAC address of the server, the MAC address must be defined manually. At the start of script execution, the MAC address is initialised to a “nil” value, but it can be subsequently set to any valid MAC address.

Output formats:

The three output formats are all available as read-only properties. The __toString magic method returns the Long format.

Additional properties:

The UUID version and variant are also available as read-only properties.

Exceptions

During normal operation, the following exceptions may be thrown:

• \Boondoc\uuid\InvalidBinary: The specified $uuid could not be validated as a UUID, and $namespace was false. Automatically passes $name through bin2hex () for printing.
• \Boondoc\uuid\InvalidString: The specified $uuid could not be validated as a UUID, and $namespace was false. Catch to encompass InvalidBinary as well.
• \Boondoc\uuid\InvalidNamespace: The specified $namespace could not be validated as a UUID.
• \Boondoc\uuid\InvalidAddress: When calling ::setMACAddress, the specified $macaddress could not be validated as a MAC address.
• \Boondoc\uuid\Exception: Abstract type, never thrown explicitly; catch to encompass all of the above.

These exceptions are for catching only, and should never need to be thrown explicitly.

All of the above exceptions feature a new method, getValue (), which returns the offending value without the rest of the message string.

Examples

Notes:

1. If the default namespace is never set, it defaults to the “nil” UUID '00000000-0000-0000-0000-000000000000'.
2. RFC 4122 Appendix C suggests some predefined namespaces. Constants defined by this library are:
   • UUID_NAMESPACE_NIL ≈ '00000000-0000-0000-0000-000000000000'
   • 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' Note that these constants are actually defined as Binary strings, and will produce unexpected results when passed as the $uuid parameter of a namespaced UUID.
3. uuid::isValid () returns true if the argument is a uuid object, or if any of ::isValidLong (), ::isValidShort () or ::isValidBinary () would return true.