Laravel Binary Uuid Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/laravel-binary-uuid
   

   Add to config/app.php under providers:

   Spatie\BinaryUuid\BinaryUuidServiceProvider::class,
   

2. Migration: Use binaryUuid() column type in migrations:

   Schema::create('users', function (Blueprint $table) {
       $table->binaryUuid('id')->primary();
       // ...
   });
   

3. Model Configuration: Extend Spatie\BinaryUuid\BinaryUuid trait in your model:

   use Spatie\BinaryUuid\BinaryUuid;
   
   class User extends Model
   {
       use BinaryUuid;
   }
   

First Use Case

Replace a standard UUID primary key with binary UUID in a new table:

php artisan make:model Post -m

Update the migration:

Schema::create('posts', function (Blueprint $table) {
    $table->binaryUuid('id')->primary();
    $table->string('title');
    $table->timestamps();
});

Run migration:

php artisan migrate

Implementation Patterns

Core Workflows

1. Model Integration:

   • Use BinaryUuid trait for automatic type casting.
   • Binary UUIDs are stored as binary(16) in MySQL, improving indexing performance.

2. Query Building:

   • Works seamlessly with Eloquent queries:

     User::where('id', $binaryUuid)->first();
     

   • Supports UUID string literals in queries:

     User::where('id', '123e4567-e89b-12d3-a456-426614174000')->first();
     

3. UUID Generation:

   • Use Str::uuid() or BinaryUuid::generate():

     $uuid = BinaryUuid::generate(); // Returns binary UUID
     $uuidString = $uuid->toString(); // Convert to string
     

4. Relationships:

   • Foreign keys should use binaryUuid() in migrations:

     $table->binaryUuid('user_id')->index();
     

Integration Tips

• Seeding: Use BinaryUuid::generate() in seeders for consistent UUIDs.
• APIs: Return UUIDs as strings in JSON responses (e.g., toString()).
• Testing: Mock binary UUIDs with BinaryUuid::generate() for predictable test data.

Gotchas and Tips

Pitfalls

1. Database Compatibility:

   • Only works with MySQL (uses binary(16)). PostgreSQL/SQLite require alternatives like michaeldyrynda/laravel-efficient-uuid.
   • Ensure your database collation supports binary UUIDs (e.g., utf8mb4_bin for MySQL).

2. Legacy Systems:

   • Binary UUIDs cannot be directly compared with string UUIDs in queries. Always use toString() for comparisons:

     // ❌ Avoid:
     User::where('id', '123e4567-e89b-12d3-a456-426614174000')->first(); // Works but risky
     
     // ✅ Prefer:
     $binaryUuid = BinaryUuid::fromString('123e4567-e89b-12d3-a456-426614174000');
     User::where('id', $binaryUuid)->first();
     

3. Serialization:

   • Binary UUIDs may not serialize/deserialize cleanly in some contexts (e.g., Redis). Use toString() before storing.

Debugging

• Query Issues: Use DB::enableQueryLog() to verify binary UUID queries:

  DB::enableQueryLog();
  User::where('id', $binaryUuid)->first();
  dd(DB::getQueryLog());
  

• Migration Errors: Ensure binaryUuid() is used in migrations, not uuid() or string.

Extension Points

1. Custom Generators:

   • Override generateBinaryUuid() in models for custom UUID logic:

     protected static function generateBinaryUuid()
     {
         return BinaryUuid::fromString('custom-prefix-' . Str::uuid());
     }
     

2. Hybrid Models:

   • Mix with other traits (e.g., HasUuid) by implementing getKeyType():

     public function getKeyType()
     {
         return 'binary-uuid';
     }
     

3. Caching:

   • Cache binary UUIDs as strings to avoid repeated conversions:

     cache()->put("user:{$user->id->toString()}", $user, now()->addHours(1));
     

Maintenance Note

• Deprecation: Since this package is unmaintained, consider migrating to michaeldyrynda/laravel-efficient-uuid for long-term projects. Key differences:
  • Supports PostgreSQL/SQLite.
  • More active development.
  • Additional features (e.g., UUIDv7 support).