API Reference - UUID Library v1.3.0

Complete reference for all UUID generation methods, constants, and utility functions.

Static Generation Methods

v1() - Time-based UUID

use Webpatser\Uuid\Uuid;
 
// Generate v1 UUID (time-based with MAC address)
$uuid = Uuid::generate(1);
echo $uuid; // e.g., 1ec9414c-232a-6dfa-883c-0242ac130003

v3() - Name-based MD5 UUID

use Webpatser\Uuid\Uuid;
 
// Generate v3 UUID (MD5 hash of namespace + name)
$uuid = Uuid::generate(3, 'example.com', Uuid::NS_DNS);
echo $uuid; // Always: 9073926b-929f-31c2-abc9-fad77ae3e8eb

v4() - Random UUID

use Webpatser\Uuid\Uuid;
 
// Generate v4 UUID (completely random)
$uuid = Uuid::v4();
echo $uuid; // e.g., 3c6e0b8a-b9c6-4c8e-9c4a-8f9e7d6c5b4a

v5() - Name-based SHA1 UUID

use Webpatser\Uuid\Uuid;
 
// Generate v5 UUID (SHA1 hash of namespace + name)
$uuid = Uuid::generate(5, 'example.com', Uuid::NS_DNS);
echo $uuid; // Always: cfbff0d1-9375-5685-968c-48ce8b15ae17

v6() - Reordered Time UUID

use Webpatser\Uuid\Uuid;
 
// Generate v6 UUID (reordered timestamp for better database performance)
$uuid = Uuid::generate(6);
echo $uuid; // e.g., 1ec9414c-232a-6dfa-883c-0242ac130003

v7() - Unix Timestamp UUID

use Webpatser\Uuid\Uuid;
 
// Generate v7 UUID (Unix timestamp based)
$uuid = Uuid::v7();
echo $uuid; // e.g., 018b2c4f-df32-7000-8000-123456789abc

v8() - Custom UUID

use Webpatser\Uuid\Uuid;
 
// Generate v8 UUID (custom/experimental)
$uuid = Uuid::generate(8);
echo $uuid; // Implementation-specific format

Legacy Generation Method

generate() - Version-specific Generation

use Webpatser\Uuid\Uuid;
 
// Generate specific UUID versions
$uuid1 = Uuid::generate(1);                                    // v1
$uuid3 = Uuid::generate(3, 'example', Uuid::NS_DNS);          // v3
$uuid4 = Uuid::generate(4);                                    // v4
$uuid5 = Uuid::generate(5, 'example', Uuid::NS_DNS);          // v5
$uuid6 = Uuid::generate(6);                                    // v6
$uuid7 = Uuid::generate(7);                                    // v7
$uuid8 = Uuid::generate(8);                                    // v8

Special UUIDs

nil() - Nil UUID

use Webpatser\Uuid\Uuid;
 
// Generate nil UUID (all zeros)
$uuid = Uuid::nil();
echo $uuid; // 00000000-0000-0000-0000-000000000000

Predefined Namespaces

Utility Methods

validate() - UUID Validation

use Webpatser\Uuid\Uuid;
 
// Validate UUID string format
$isValid = Uuid::validate('550e8400-e29b-41d4-a716-446655440000'); // true
$isValid = Uuid::validate('invalid-uuid');                         // false
$isValid = Uuid::validate('550e8400e29b41d4a716446655440000');     // false (no hyphens)

import() - Import UUID

use Webpatser\Uuid\Uuid;
 
// Import existing UUID string
$uuid = Uuid::import('550e8400-e29b-41d4-a716-446655440000');
echo $uuid->string; // "550e8400-e29b-41d4-a716-446655440000"
echo $uuid->hex;    // "550e8400e29b41d4a716446655440000"

compare() - UUID Comparison

use Webpatser\Uuid\Uuid;
 
$uuid1 = Uuid::v4();
$uuid2 = Uuid::import($uuid1->string);
 
$areEqual = Uuid::compare($uuid1, $uuid2); // true
$areEqual = ($uuid1->string === $uuid2->string); // Also true

Instance Properties

$uuid = Uuid::v4();
 
// Different formats
echo $uuid->string;  // "550e8400-e29b-41d4-a716-446655440000"
echo $uuid->hex;     // "550e8400e29b41d4a716446655440000"
echo $uuid->bytes;   // Raw 16-byte binary data
 
// UUID components
echo $uuid->version; // 4
echo $uuid->variant; // RFC 4122 variant

Usage Examples

Namespace-based UUIDs

use Webpatser\Uuid\Uuid;
 
// Using predefined namespaces
$dnsUuid = Uuid::generate(5, 'example.com', Uuid::NS_DNS);
$urlUuid = Uuid::generate(5, 'https://example.com/page', Uuid::NS_URL);
$oidUuid = Uuid::generate(5, '1.3.6.1.4.1.343', Uuid::NS_OID);
 
// Using custom namespace
$customNamespace = Uuid::v4(); // Generate a random namespace
$customUuid = Uuid::generate(5, 'my-custom-name', $customNamespace);

Interactive API Testing

Return Types & Format

All UUID generation methods return a string in the standard UUID format:

xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx
 
Where:
- x = hexadecimal digit (0-9, a-f)
- M = UUID version number (1-8)
- N = UUID variant bits (8, 9, A, or B)

Standards Compliance

• RFC 4122: Versions 1, 3, 4, 5
• RFC 9562: Versions 6, 7, 8 (draft standard)
• Format: 36-character string with hyphens
• Encoding: Hexadecimal lowercase

Error Handling

use Webpatser\Uuid\Uuid;
use InvalidArgumentException;
 
try {
    // Invalid namespace
    $uuid = Uuid::v5('invalid-namespace', 'name');
} catch (InvalidArgumentException $e) {
    echo "Error: " . $e->getMessage();
}
 
try {
    // Invalid UUID string
    $uuid = Uuid::import('not-a-uuid');
} catch (InvalidArgumentException $e) {
    echo "Error: " . $e->getMessage();
}