UUID Library v1.3.0

Quick Start Guide

webpatser@dev: ~/uuid/1.3.0 $ cat quick-start.md

Quick Start - UUID Library v1.3.0

Get started with high-performance UUID generation in minutes. This guide covers the most common use cases with live examples.

Basic UUID Generation

The most common UUIDs you'll need:

 
use Webpatser\Uuid\Uuid;
 
// Random UUID (most common)
$uuid4 = Uuid::v4();
echo $uuid4; // e.g., "550e8400-e29b-41d4-a716-446655440000"
 
// Timestamp-based UUID (database optimized)
$uuid7 = Uuid::v7();
echo $uuid7; // e.g., "018f4e7c-8b3a-7000-8000-123456789abc"

Live Generation Comparison

UUID v4 (Random)

3cceddae-411d-473c-b048-521cbf8860e3
fce1d0ad-6bd5-4068-849c-b494d5fe4bfb
86955fc7-78c6-40d2-9579-eb2caa1b7fb4

Notice: Completely random

UUID v7 (Timestamp)

019c2686-1add-700c-a97a-28698e7783bc
019c2686-1add-7011-92fc-02fe11844406
019c2686-1add-7023-86c5-e4d7318de14d

Notice: Sequential ordering

Working with UUIDs

Access different formats and validate UUIDs:

 
$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
 
// Validation
$isValid = Uuid::validate('550e8400-e29b-41d4-a716-446655440000'); // true
$isValid = Uuid::validate('invalid-uuid'); // false
 
// Import existing UUIDs
$imported = Uuid::import('550e8400-e29b-41d4-a716-446655440000');

UUID Versions Explained

Version Type Use Case Example
v1 Time + MAC Legacy systems e9fabb90-0172-11f1-846b-d3c4e2ecb4e4
v4 Random General purpose ✓ 65a39c06-c7a5-4699-95da-1bc7410f2d48
v7 Timestamp Database optimized ✓ 019c2686-1add-703e-8b68-ce4f23af3dc2

Name-Based UUIDs

Generate deterministic UUIDs from names:

 
// MD5-based (v3)
$uuid3 = Uuid::generate(3, 'example.com', Uuid::NS_DNS);
 
// SHA-1-based (v5) - recommended
$uuid5 = Uuid::generate(5, 'example.com', Uuid::NS_DNS);
 
// Same input = same UUID
$same = Uuid::generate(5, 'example.com', Uuid::NS_DNS);
// $uuid5 === $same (true)

Live Name-Based Example

Input: "example.com" → cfbff0d1-9375-5685-968c-48ce8b15ae17
Input: "example.com" → cfbff0d1-9375-5685-968c-48ce8b15ae17

Same input produces identical UUIDs (deterministic)

Performance Tips

  • Use v4 for general purpose: Maximum randomness, good performance
  • Use v7 for databases: Natural sorting order improves indexing
  • Batch operations: Generate multiple UUIDs in loops efficiently
  • Cache when possible: Store UUIDs rather than regenerating
 
// Efficient batch generation
$uuids = [];
for ($i = 0; $i < 1000; $i++) {
$uuids[] = Uuid::v7(); // Maintains chronological order
}
 
// Benchmark different versions
$start = microtime(true);
for ($i = 0; $i < 10000; $i++) {
Uuid::v4();
}
$time = (microtime(true) - $start) * 1000;
echo "Generated 10k v4 UUIDs in {$time}ms";

Next Steps