Uid Laravel Package

Technical Evaluation

Architecture Fit

• Strong Fit for Laravel:

  • Symfony’s UID component is Laravel-agnostic but Laravel-compatible, integrating seamlessly with Eloquent models, API resources, and database layers.
  • Supports binary storage (PostgreSQL UUID, MySQL BINARY(16)), aligning with Laravel’s modern database practices.
  • Object-oriented API meshes well with Laravel’s dependency injection (DI) and service container, enabling clean integration via bindings or facades.
  • Time-ordered IDs (UUIDv7/ULID) solve Laravel’s auto-increment limitations in distributed environments (e.g., multi-DC deployments, serverless).

• Key Synergies:

  • Eloquent Models: Replace incrementing IDs with Uuid traits or custom accessors (e.g., $model->getRouteKey()).
  • APIs: Leverage Uuid::toRfc9562() for RFC-compliant payloads (e.g., GraphQL, JSON:API).
  • Testing: MockUuidFactory integrates with Laravel’s testing tools (Pest, PHPUnit) for deterministic UUIDs in CI.
  • Caching: Binary UIDs reduce Redis/Memcached payload sizes by ~60% vs. string UUIDs.

• Anti-Patterns to Avoid:

  • Over-engineering: Avoid using ULIDs/UUIDv7 for simple CRUD apps where auto-increment suffices.
  • Database Migrations: Requires careful planning for existing tables (e.g., ALTER TABLE users ADD COLUMN id BINARY(16)).

Integration Feasibility

• Laravel Ecosystem Compatibility:

  • PHP 8.1+: Required for v7.4.x; v8.0.x requires PHP 8.4+. Laravel 10+ supports both.
  • Database Drivers: Works with PostgreSQL, MySQL 8.0+, SQLite (via BLOB), and SQL Server.
  • ORM/ODM: Eloquent, Doctrine, and API Platform integrations are well-documented.
  • Serialization: Plays nicely with Laravel’s JSON responses, XML, and API resources.

• Dependency Conflicts:

  • Low Risk: Symfony UID is a lightweight (~1MB) component with minimal dependencies (only ext-ds for Hashable in some cases).
  • Potential Conflicts:
    • Avoid mixing with ramsey/uuid (use one or the other).
    • Ensure no duplicate symfony/polyfill versions in composer.json.

• Customization Points:

  • UID Factories: Extend UuidFactory or UlidFactory for custom logic (e.g., namespace prefixes).
  • Validation Rules: Use Uuid::isValid() in Laravel’s FormRequest or Validator.
  • Database Types: Configure getType() in Eloquent models for binary storage.

Technical Risk

• Critical Questions:
  1. Database Support: Does your DB support binary storage for UUIDs/ULIDs? (e.g., MySQL 8.0+, PostgreSQL).
  2. ID Length Constraints: Will BASE_58 or RFC 9562 formats fit your API payload limits?
  3. Time-Sensitivity: Do you need microsecond precision (UUIDv7) or sortable timestamps (ULID)?
  4. Legacy Systems: How will existing APIs/clients handle the new ID formats?
  5. Compliance: Are sequential IDs a privacy risk (e.g., exposing user counts)?

Integration Approach

Stack Fit

• Laravel-Specific Integrations:

  • Eloquent Models:

    use Symfony\Uid\Uuid;
    use Illuminate\Database\Eloquent\Model;
    
    class User extends Model {
        protected $keyType = 'string';
        protected $incrementing = false;
        protected $casts = ['id' => Uuid::class];
    
        protected static function boot() {
            parent::boot();
            static::creating(function ($model) {
                $model->id = Uuid::v7(); // or Uuid::v4(), Ulid::generate()
            });
        }
    }
    

  • API Resources:

    use Symfony\Uid\Uuid;
    use Illuminate\Http\Resources\Json\JsonResource;
    
    class UserResource extends JsonResource {
        public function toArray($request) {
            return [
                'id' => $this->resource->id->toRfc9562(), // RFC 9562 format
                'name' => $this->name,
            ];
        }
    }
    

  • Validation:

    use Symfony\Uid\Uuid;
    use Illuminate\Validation\Rule;
    
    $request->validate([
        'uuid' => ['required', Rule::function('uuid')->make(function ($attribute, $value) {
            return Uuid::isValid($value);
        })],
    ]);
    

• Symfony Ecosystem:

  • If using API Platform, Mercure, or Messenger, UID integrates natively for message IDs, event sourcing, and WebSocket channels.
  • Serializer: Supports @Groups and normalization contexts for API responses.

Migration Path

1. Phase 1: Pilot Project

   • Adopt in a non-critical module (e.g., analytics, notifications).
   • Test binary storage, performance, and API compatibility.
   • Example: Replace id in analytics_events table with ULID.

2. Phase 2: Core Models

   • Migrate high-traffic models (e.g., users, orders) with dual-column support:

     ALTER TABLE users ADD COLUMN uuid BINARY(16);
     UPDATE users SET uuid = UNHEX(REPLACE(id, '-', ''));
     

   • Update Eloquent models to use Uuid trait or custom accessors.

3. Phase 3: Full Adoption

   • Deprecate auto-increment IDs in new features.
   • Use database views or triggers to maintain legacy ID lookups temporarily.

Compatibility

Sequencing

1. Add UID Column:

   php artisan make:migration add_uuid_to_users_table --table=users
   

   public function up() {
       Schema::table('users', function (Blueprint $table) {
           $table->binary('uuid')->after('id')->unique();
       });
   }
   

2. Backfill UIDs:

   User::chunk(1000, function ($users) {
       foreach ($users as $user) {
           $user->uuid = Uuid::fromString($user->id)->toBinary();
           $user->save();
       }
   });
   

3. Update Models:

   class User extends Model {
       protected $keyType = 'string';
       public $incrementing = false;
       protected $casts = ['uuid' => Uuid::class];
   }
   

4. Deprecate Legacy IDs:
   • Add scopeByLegacyId() for temporary compatibility.
   • Remove id column in a future migration.

Operational Impact

Maintenance

• **Pro