Uuid Generator Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require da-vinci-studio/uuid-generator
   

   Add the service provider to config/app.php under providers:

   DaVinciStudio\UuidGenerator\UuidServiceProvider::class,
   

2. First Usage Generate a UUID via the facade (auto-registered):

   use DaVinciStudio\UuidGenerator\Facades\Uuid;
   
   $uuid = Uuid::generate(); // e.g., "550e8400-e29b-41d4-a716-446655440000"
   

3. Key Classes

   • Uuid::generate() – Default UUIDv4.
   • Uuid::generateVersion($version) – Generate UUIDv1/v3/v4/v5.
   • Uuid::isValid($uuid) – Validate UUID format.

First Use Case

Replace auto-increment IDs in a users table migration:

Schema::create('users', function (Blueprint $table) {
    $table->uuid('id')->primary(); // No need for $table->increments('id')
});

Implementation Patterns

Workflows

1. Database Integration Use with Laravel’s uuid column type (requires doctrine/dbal):

   use Illuminate\Support\Facades\Schema;
   
   Schema::table('posts', function (Blueprint $table) {
       $table->uuid('uuid')->after('id')->unique();
   });
   

2. Model UUIDs Cast attributes to UUIDs in models:

   protected $casts = [
       'external_id' => 'uuid',
   ];
   

3. API Responses Normalize UUIDs in JSON responses:

   return response()->json([
       'data' => [
           'id' => Uuid::generate(), // Ensures consistent format
           'name' => 'Example',
       ],
   ]);
   

Integration Tips

• Validation: Use Uuid::isValid() in Form Requests:

  public function rules()
  {
      return [
          'external_id' => 'required|uuid',
      ];
  }
  

• Seeding: Generate UUIDs in DatabaseSeeder:

  factory(App\User::class)->create([
      'uuid' => Uuid::generate(),
  ]);
  

• Legacy Migration: Convert existing integer IDs to UUIDs:

  $user->update(['uuid' => Uuid::generate()]);
  

Gotchas and Tips

Pitfalls

1. No UUIDv7 Support The package lacks UUIDv7 (time-sortable), which is useful for event sourcing. Consider ramsey/uuid for advanced use cases.

2. Database Indexing UUIDs are longer than integers. Ensure proper indexing (e.g., BTREE for MySQL) for performance:

   $table->uuid('id')->primary()->index();
   

3. Version Confusion UUIDv1 uses MAC addresses (deprecated for privacy). Prefer UUIDv4 for most cases:

   Uuid::generateVersion(4); // Explicitly specify version
   

Debugging

• Validation Errors: Uuid::isValid() rejects hyphen-less UUIDs. Normalize input:

  $uuid = str_replace('-', '', $uuid); // Remove hyphens before validation
  

• Collision Risk: UUIDv4 has a 1-in-2¹²² chance of collision. Monitor duplicates in production.

Extension Points

1. Custom Generators Extend the generator class:

   use DaVinciStudio\UuidGenerator\Generators\UuidGenerator;
   
   class CustomUuidGenerator extends UuidGenerator {
       public function generate()
       {
           return parent::generateVersion(5, 'namespace', 'name');
       }
   }
   

   Register in UuidServiceProvider.

2. Hybrid IDs Combine UUIDs with timestamps for sorting:

   $hybridId = (string) Uuid::generate() . '-' . now()->timestamp;