Uuid Laravel Package

Getting Started

Install the package via Composer:

composer require webpatser/uuid

First use case: Generate a UUIDv7 for a new database record (recommended for Laravel models):

use Webpatser\Uuid\Uuid;

$uuid = Uuid::v7(); // Time-ordered, database-friendly
$model = new User(['id' => $uuid]);

Where to look first:

• Quick Start in the README for generation methods
• API Reference for validation/comparison methods
• SQL Server Support if using Microsoft SQL Server

Implementation Patterns

Laravel Model Integration

use Illuminate\Database\Eloquent\Model;
use Webpatser\Uuid\Uuid;

class User extends Model
{
    protected $keyType = 'string';
    public $incrementing = false;

    protected static function boot()
    {
        parent::boot();

        static::creating(function ($model) {
            $model->{$model->getKeyName()} = Uuid::v7();
        });
    }
}

UUIDv7 for Database Optimization

// Generate UUIDv7 for time-ordered records
$uuid = Uuid::v7();

// Access properties
$timestamp = $uuid->time; // Unix timestamp
$string = $uuid->string;  // Standard UUID string

Validation in Laravel Requests

use Illuminate\Foundation\Http\FormRequest;
use Webpatser\Uuid\Uuid;

class StoreUserRequest extends FormRequest
{
    public function rules()
    {
        return [
            'uuid' => 'required|uuid',
        ];
    }

    public function validateUuidAttribute($attribute, $value)
    {
        return Uuid::validate($value) || $this->fail("Invalid UUID format");
    }
}

SQL Server Compatibility

// Import from SQL Server
$uuid = Uuid::importFromSqlServer('825B076B-44EC-E511-80DC-00155D0ABC54');

// Export to SQL Server format
$sqlGuid = $uuid->toSqlServer();

UUIDv4 for Security Tokens

// Generate secure random UUID for API tokens
$token = Uuid::v4();

// Validate in middleware
if (!Uuid::validate($request->bearerToken)) {
    abort(401);
}

Gotchas and Tips

Common Pitfalls

1. PHP Version Requirement: Requires PHP 8.5+ (throws fatal error on older versions)
2. UUIDv1 MAC Address: Avoid UUIDv1 in production (uses MAC address which may violate privacy policies)
3. SQL Server Endianness: Always use importFromSqlServer() when working with SQL Server GUIDs
4. Validation Strictness: Uuid::validate() is case-sensitive for hex characters (use strtolower() if needed)

Debugging Tips

• Use Uuid::benchmark() to compare performance between versions
• Check uuid->version property to verify correct UUID version was generated
• For validation issues, use Uuid::import() to convert strings before comparison

Configuration Quirks

• No package configuration needed (pure PHP implementation)
• For Laravel, ensure your database connection supports UUID types (PostgreSQL/MySQL 8.0+ recommended)

Extension Points

1. Custom UUID Version: Extend the Uuid class to support additional versions
2. Database Casting: Create a custom Eloquent cast for UUID operations
3. Validation Rules: Add custom Laravel validation rules for UUID formats
4. Benchmarking: Use the built-in benchmarking to compare performance with other libraries

Performance Considerations

• UUIDv7 is ~20% slower than UUIDv4 but provides database ordering benefits
• For maximum performance, cache frequently used UUIDs (e.g., nil UUID)
• UUIDv3/v5 are significantly slower due to hashing operations

Testing Tips

• Use Uuid::nil() for testing placeholder records
• Mock UUID generation in tests by replacing Uuid::generate() with static methods
• Test SQL Server conversion with known GUID values from your database