Cuid2 Laravel Package

Technical Evaluation

Architecture Fit

• Strengths:
  • Distributed ID Generation: Ideal for Laravel microservices or multi-process environments where UUIDv4 coordination is impractical.
  • Sortability: Timestamp-based prefixes enable chronological queries (e.g., ORDER BY id in databases).
  • URL Safety: Base36 encoding avoids special characters, simplifying API routes (e.g., /users/{cuid}).
  • Collision Resistance: SHA3-512 hashing + fingerprinting mitigates edge cases (e.g., rapid generation bursts).
  • Configurable Length: Aligns with domain needs (e.g., 10-char IDs for feature flags vs. 24-char for primary keys).
• Weaknesses:
  • No Built-in Indexing: Unlike ULIDs, CUID2 lacks native epoch encoding for time-range queries (requires SUBSTRING or custom indexing).
  • GMP Dependency: Hard requirement for optimal performance (though fallback exists). May conflict with shared hosting or Docker constraints.
  • No Versioning in IDs: Unlike ULIDs, CUID2 lacks a timestamp component that can be parsed for time-based analytics.

Integration Feasibility

• Laravel Compatibility:
  • Eloquent Models: Replace uuid() or ulid() with Cuid2::generate() in model bootstraps or factories.
  • Database Schemas: Ensure columns use CHAR(24) (default) or CHAR(N) for custom lengths (e.g., CHAR(10)).
  • APIs: Works seamlessly with Laravel’s routing (e.g., Route::get('/users/{cuid}', ...)).
• Migration Path:
  • Backward Compatibility: CUID2 is not a drop-in replacement for UUIDs/ULIDs (format differs). Requires schema updates.
  • Hybrid Approach: Use alongside existing IDs (e.g., cuid + uuid columns) during transition.
  • Validation: Cuid2::isValid() can enforce format constraints in API payloads or database constraints.

Technical Risk

• Critical Risks:
  • GMP Dependency: If ext-gmp is unavailable, performance degrades 300x (SHA3-512 + base36 conversion becomes a bottleneck). Mitigate by:
    • Documenting the requirement in composer.json or README.
    • Providing a performance benchmark in CI (e.g., phpbench).
  • Fingerprint Collisions: Rare but possible if multiple processes share the same hostname/PID. Mitigate by:
    • Extending Fingerprint to include additional entropy (e.g., getmypid() + microtime()).
    • Monitoring collision rates in production (log generation failures).
  • Sorting Limitations: Without a parsed timestamp, range queries (e.g., "IDs from last hour") require full-table scans. Mitigate by:
    • Adding a created_at column for time-based queries.
    • Using a database function to extract the timestamp prefix (e.g., SUBSTRING(id, 2, 13) for Unix epoch).
• Moderate Risks:
  • Length Constraints: Custom lengths (e.g., 10 chars) may reduce collision resistance. Validate against domain requirements.
  • Validation Overhead: Cuid2::isValid() adds CPU cost; cache results if used frequently (e.g., in API middleware).
  • PHP 8.2+ Requirement: Blocks integration with legacy Laravel apps (<8.2). Mitigate by:
    • Creating a feature flag or branch for older PHP versions.
    • Evaluating alternatives like ramsey/uuid for mixed environments.

Key Questions

1. Performance Requirements:
   • What is the expected throughput of ID generation (e.g., IDs/sec)? If >10K/sec, GMP is mandatory.
   • Are IDs generated in high-frequency loops (e.g., event sourcing)? If yes, benchmark with/without GMP.
2. Database Schema:
   • Should CUID2 replace all UUIDs/ULIDs, or only specific entities (e.g., only for public-facing routes)?
   • Will the team need to query by time ranges? If yes, consider hybrid storage (CUID2 + created_at).
3. Deployment Constraints:
   • Can ext-gmp be installed in production? If not, is the performance tradeoff acceptable?
   • Are there shared hosting or Docker constraints that limit extensions?
4. Validation Needs:
   • Should CUID2 validation be enforced at the API layer, database layer, or both?
   • Are there legacy systems that might generate malformed IDs?
5. Monitoring:
   • Should the team track collision rates or generation failures in production?
   • Are there SLOs for ID generation latency (e.g., P99 < 1ms)?

Integration Approach

Stack Fit

• Laravel-Specific Synergies:
  • Service Providers: Register Cuid2 as a singleton for dependency injection:

    // app/Providers/AppServiceProvider.php
    public function register(): void {
        $this->app->singleton(Cuid2::class, fn() => new Cuid2());
    }
    

  • Model Events: Auto-generate CUID2 in creating() hooks:

    protected static function boot(): void {
        static::creating(fn($model) => $model->id = app(Cuid2::class));
    }
    

  • API Resources: Use Cuid2::generate() in factories or controllers:

    // app/Http/Controllers/UserController.php
    public function store(Request $request) {
        $user = User::create(['id' => Cuid2::generate(), ...]);
        return response()->json($user);
    }
    

  • Database: Use CHAR(24) columns (not VARCHAR) for fixed-length storage:

    Schema::create('users', fn(Blueprint $table) => {
        $table->char('id', 24)->primary();
        $table->timestamps();
    });
    

• Testing:
  • Unit Tests: Mock Cuid2 to return deterministic values:

    $mock = Mockery::mock(Cuid2::class)->makePartial();
    $mock->shouldReceive('toString')->andReturn('test123');
    $this->app->instance(Cuid2::class, $mock);
    

  • Integration Tests: Verify ID uniqueness and format in feature tests.

Migration Path

1. Phase 1: Pilot (Low Risk)
   • Scope: Non-critical tables (e.g., audit logs, feature flags).
   • Actions:
     • Add cuid column to a secondary table (e.g., users_cuid).
     • Use Cuid2::generate() in application logic alongside existing IDs.
     • Validate collisions in production (log duplicates).
   • Tools: Laravel migrations + Schema::table()->addColumn().
2. Phase 2: Hybrid (Medium Risk)
   • Scope: Public-facing APIs or high-collision-risk entities.
   • Actions:
     • Replace UUIDs in API routes (e.g., /users/{cuid}).
     • Update database indexes to include CUID2 columns.
     • Deprecate old UUID routes with redirects.
   • Tools: Laravel’s Route::aliasMethod() for transitional routing.
3. Phase 3: Full Migration (High Risk)
   • Scope: Core entities (e.g., users, orders).
   • Actions:
     • Backfill CUID2 into existing tables (batch job).
     • Update all queries to use CUID2 (e.g., WHERE id = ?).
     • Deprecate UUID generation entirely.
   • Tools: Laravel’s DB::statement() for bulk updates.

Compatibility

• Laravel Ecosystem:
  • Scout: CUID2 works with Laravel Scout (no format conflicts).
  • Cashier/Invoices: Replace UUIDs in payment references (e.g., invoice_id).
  • Nova/Vue: Display CUID2 in admin panels (no UI changes needed).
• Third-Party Packages:
  • UUID Packages: Avoid conflicts by namespacing (e.g., Ramsey\Uuid\Uuid vs. Visus\Cuid2\Cuid2).
  • Database Packages: Ensure packages like spatie/laravel-activitylog support CUID2.
• Legacy Systems:
  • Use mapping tables to translate between UUIDs and CUID2 during transition.

Sequencing

1. Pre-Migration:
   • Benchmark Cuid2 generation in staging (with/without GMP).
   • Update composer.json to require PHP 8.2+ and ext-gmp (if critical).
   • Add CUID2 to CI checks (e.g., phpunit, pest).
2. Pilot Phase:
   • Implement in a single service (e.g.,