Quick Start - Laravel UUID v6.2.0

Get up and running with high-performance UUIDs in Laravel. This package provides 15-25% faster UUID generation with seamless Laravel integration.

Three Ways to Use UUIDs

Choose the approach that best fits your needs:

Option 1: High-Performance Str Macros (Recommended)

Drop-in replacements for Laravel's built-in UUID methods with better performance:

use Illuminate\Support\Str;
 
// 15% faster than Str::uuid()
$uuid = Str::fastUuid();
echo $uuid; // "550e8400-e29b-41d4-a716-446655440000"
 
// 25% faster than Str::orderedUuid()
$ordered = Str::fastOrderedUuid();
echo $ordered; // "018f4e7c-8b3a-7000-8000-123456789abc"
 
// Fast validation
if (Str::fastIsUuid($someString)) {
    echo "Valid UUID!";
}
 
// Additional UUID versions
$timeUuid = Str::timeBasedUuid();       // V1 time-based
$nameUuid = Str::nameUuidSha1('example.com'); // V5 name-based
$customUuid = Str::customUuid('data');  // V8 custom

Option 2: Direct Library Access (Maximum Performance)

Access the core UUID library directly for maximum speed:

use Webpatser\Uuid\Uuid;
 
$uuid4 = Uuid::v4();                    // Random UUID
$uuid7 = Uuid::v7();                    // Database-optimized
$uuid1 = Uuid::generate(1);             // Time-based
$uuid5 = Uuid::generate(5, 'example.com', Uuid::NS_DNS);
 
// Validation and utility methods
$isValid = Uuid::validate($uuid);
$version = $uuid->version;              // Get UUID version
$timestamp = $uuid->getTimestamp();     // For time-based UUIDs

Option 3: Global Facade

Use the auto-registered global facade:

// No import needed - facade is auto-registered
$uuid4 = Uuid::v4();
$uuid7 = Uuid::v7();
$isValid = Uuid::validate($someUuid);
$nil = Uuid::nil();

Laravel Validation

Laravel's built-in UUID validation works perfectly with our UUIDs:

// In your form requests or controllers
$rules = [
    'user_id' => 'required|uuid',
    'session_id' => 'nullable|uuid:4',    // Specific to UUID v4
    'legacy_id' => 'uuid:1',              // Version 1 only
];
 
// Custom validation using our library
use Webpatser\Uuid\Uuid;
 
$rules = [
    'custom_uuid' => [
        'required',
        function ($attribute, $value, $fail) {
            if (!Uuid::validate($value)) {
                $fail("The {$attribute} must be a valid UUID.");
            }
        },
    ],
];

Route Model Binding

UUIDs work seamlessly with Laravel's route model binding:

// routes/web.php
Route::get('/user/{user}', function (User $user) {
    return view('user.profile', compact('user'));
});
 
// Works with both string and binary UUIDs:
// /user/550e8400-e29b-41d4-a716-446655440000

Working with Different UUID Versions

Performance Comparison Examples

// Benchmark UUID generation
$start = microtime(true);
 
// Old Laravel way (slower)
for ($i = 0; $i < 10000; $i++) {
    $uuid = Str::uuid();  // Uses Ramsey UUID
}
$laravelTime = (microtime(true) - $start) * 1000;
 
$start = microtime(true);
 
// Our high-performance way (15% faster)
for ($i = 0; $i < 10000; $i++) {
    $uuid = Str::fastUuid();  // Uses our library
}
$ourTime = (microtime(true) - $start) * 1000;
 
echo "Laravel: {$laravelTime}ms\n";
echo "Our library: {$ourTime}ms\n";
echo "Performance gain: " . round(($laravelTime - $ourTime) / $laravelTime * 100, 1) . "%\n";

Common Patterns

Generate Multiple UUIDs

// Efficient batch generation
$uuids = [];
for ($i = 0; $i < 1000; $i++) {
    $uuids[] = Str::fastOrderedUuid(); // V7 for better DB performance
}
 
// Or collect with Laravel helpers
$userIds = collect(range(1, 100))
    ->map(fn() => Str::fastUuid())
    ->toArray();

Deterministic UUIDs

// Generate same UUID for same input
$userId = Str::nameUuidSha1("[email protected]");
$sameUserId = Str::nameUuidSha1("[email protected]");
// $userId === $sameUserId (always true)
 
// Custom namespace
$customNamespace = Uuid::v4();
$appUuid = Uuid::generate(5, 'my-app-data', $customNamespace);

UUID Utilities

$uuid = Str::fastUuid();
 
// Get UUID information
$version = Str::uuidVersion($uuid);     // 4
$isNil = Str::isNilUuid($uuid);        // false
$timestamp = Str::uuidTimestamp($uuid); // For time-based UUIDs
 
// Format conversions
$binary = Str::uuidToBinary($uuid);     // 16 bytes
$backToString = Str::binaryToUuid($binary);

Next Steps