Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
A PHP 5.3+ library for generating RFC 4122 version 1, 3, 4, and 5 universally unique identifiers (UUID). Requires a 64-bit build of PHP.
PHP
Branch: feature/valida…
Pull request Compare This branch is 1 commit ahead, 190 commits behind ramsey:2.8.

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
src/Rhumsaa/Uuid
tests
.gitignore
.travis.yml
LICENSE
README.md
composer.json
phpunit.xml.dist

README.md

Rhumsaa\Uuid

Build Status

A PHP 5.3+ library for generating and working with RFC 4122 version 1, 3, 4, and 5 universally unique identifiers (UUID).

Much inspiration for this library came from the Java and Python UUID libraries.

Requirements

Rhumsaa\Uuid works on 64-bit builds of PHP 5.3.3+.

This library deals with large integers, so you will need to run it on a 64-bit system with a 64-bit compiled version of PHP.

Warning: The Windows binaries located on PHP.net are 32-bit versions of PHP. Even if you run them on a 64-bit version of Windows, this library will not work. You will need to compile PHP on Windows yourself to build a 64-bit version.

Examples

<?php
use Rhumsaa\Uuid\Uuid;

// Generate a version 1 (time-based) UUID
$uuid1 = Uuid::uuid1();
echo $uuid1 . "\n"; // e4eaaaf2-d142-11e1-b3e4-080027620cdd

// Generate a version 3 (name-based and hashed with MD5) UUID
$uuid3 = Uuid::uuid3(Uuid::NAMESPACE_DNS, 'php.net');
echo $uuid3 . "\n"; // 11a38b9a-b3da-360f-9353-a5a725514269

// Generate a version 4 (random) UUID
$uuid4 = Uuid::uuid4();
echo $uuid4 . "\n"; // 25769c6c-d34d-4bfe-ba98-e0ee856f3e7a

// Generate a version 5 (name-based and hashed with SHA1) UUID
$uuid5 = Uuid::uuid5(Uuid::NAMESPACE_DNS, 'php.net');
echo $uuid5 . "\n"; // c4a760a8-dbcf-5254-a0d9-6a4474bd1b62

Library API

Creation methods

Each of the following methods are called statically to create Uuid objects. The class constructor cannot be used to create Uuid objects. That is, the use of new Uuid() is disabled.

Uuid Uuid::fromString($name)
Creates a UUID from the string standard representation

Example:

$uuid = Uuid::fromString('fa018870-d1f6-11e1-9b23-0800200c9a66');

Uuid Uuid::uuid1()
Creates a time-based UUID (version 1)

Uuid Uuid::uuid3($namespace, $name)
Creates a UUID (version 3) based on the MD5 hash of a namespace identifier and a name

Uuid Uuid::uuid4() Creates a random UUID (version 4)

Uuid Uuid::uuid5($namespace, $name)
Creates a UUID (version 5) based on the SHA-1 hash of a namespace identifier and a name

Instance methods

Once you have a Uuid object, you may call the following methods on the object.

int compareTo(Uuid $uuid)
Compares this UUID with the specified UUID. The first of two UUIDs is greater than the second if the most significant field in which the UUIDs differ is greater for the first UUID.

Returns -1 if this UUID is less than the compared to UUID, 0 if it is equal to the compared to UUID, and 1 if it is greater than the compared to UUID.

Example:

$uuid1 = Uuid::fromString('44cca71e-d13d-11e1-a959-c8bcc8a476f4');
$uuid2 = Uuid::fromString('44cca71e-d13d-11e2-a959-c8bcc8a476f4');
switch ($uuid1->compareTo($uuid2)) {
    case -1:
        echo "$uuid1 is less than $uuid2";
        break;
    case 1:
        echo "$uuid1 is greater than $uuid2";
        break;
    case 0:
    default:
        echo "$uuid1 is equal to $uuid2";
}

bool equals($obj)
Compares this UUID to the specified object and returns true if they are equal.

string getBytes()
Returns the UUID as a 16-byte string.

int getClockSeqHiAndReserved()
Returns the high field of the clock sequence multiplexed with the variant (bits 65-72 of the UUID).

int getClockSeqLow()
Returns the low field of the clock sequence (bits 73-80 of the UUID).

int getClockSequence()
Returns the full clock sequence, including the high and low fields.

\DateTime getDateTime()
For version 1 UUIDs, this returns a PHP DateTime object representing the date and time used to create the UUID.

array getFields()
Returns an array of the fields of the UUID, with keys named according to the RFC 4122 names for the fields.

Field Meaning
time_low the first 32 bits of the UUID
time_mid the next 16 bits of the UUID
time_hi_and_version the next 16 bits of the UUID
clock_seq_hi_and_reserved the next 8 bits of the UUID
clock_seq_low the next 8 bits of the UUID
node the last 48 bits of the UUID

int getLeastSignificantBits()
Returns the least significant 64 bits of this UUID's 128 bit value.

int getMostSignificantBits()
Returns the most significant 64 bits of this UUID's 128 bit value.

int getNode()
Returns the node value associated with this UUID.

int getTimeHiAndVersion()
Returns the high field of the timestamp multiplexed with the version number (bits 49-64 of the UUID).

int getTimeLow()
Returns the low field of the timestamp (the first 32 bits of the UUID).

int getTimeMid()
Returns the middle field of the timestamp (bits 33-48 of the UUID).

int getTimestamp()
For version 1 UUIDs, this returns the 60 bit timestamp value used to create this UUID. The timestamp is measured in 100-nanosecond units since midnight, October 15, 1582, UTC. It is not a Unix timestamp.

string getUrn()
Returns the string representation of the UUID as a URN.

int getVariant()
Returns the variant number associated with this UUID.

The variant number has the following meaning:

  • 0 - Reserved for NCS backward compatibility
  • 2 - The RFC 4122 variant (used by this class
  • 6 - Reserved, Microsoft Corporation backward compatibility
  • 7 - Reserved for future definition

int getVersion()
The version number associated with this UUID. The version number describes how this UUID was generated.

The version number has the following meaning:

  • 1 - Time-based UUID
  • 2 - DCE security UUID
  • 3 - Name-based UUID hashed with MD5
  • 4 - Randomly generated UUID
  • 5 - Name-based UUID hashed with SHA-1

string toString()
Converts this UUID into a string representation. This class also implements __toString(), which will convert this object to a string when it is used in any string context.

Installation

The preferred method of installation is via Packagist, as this provides the PSR-0 autoloader functionality. The following composer.json will download and install the latest version of the Uuid library into your project:

{
    "require": {
        "rhumsaa/uuid": "*"
    }
}
Something went wrong with that request. Please try again.