mirror of
https://github.com/ramsey/uuid.git
synced 2026-06-17 16:26:51 +03:00
Ben Ramsey
209 lines
6.6 KiB
Markdown
209 lines
6.6 KiB
Markdown
# Rhumsaa\Uuid
|
|
|
|
[](http://travis-ci.org/ramsey/uuid)
|
|
|
|
A PHP 5.3+ library for generating and working with [RFC 4122][rfc4122] version
|
|
1, 3, 4, and 5 universally unique identifiers (UUID).
|
|
|
|
Much inspiration for this library came from the [Java][javauuid] and
|
|
[Python][pyuuid] 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][phpwin] 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
|
|
<?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:
|
|
|
|
```json
|
|
{
|
|
"require": {
|
|
"rhumsaa/uuid": "*"
|
|
}
|
|
}
|
|
```
|
|
|
|
|
|
[rfc4122]: http://tools.ietf.org/html/rfc4122
|
|
[javauuid]: http://docs.oracle.com/javase/6/docs/api/java/util/UUID.html
|
|
[pyuuid]: http://docs.python.org/library/uuid.html
|
|
[phpwin]: http://windows.php.net/download/
|
|
[packagist]: http://packagist.org/
|