Optimus Laravel Package

Technical Evaluation

Architecture Fit

• Id Obfuscation Use Case: Optimus is a perfect fit for replacing sequential database IDs (e.g., auto-incremented id columns) with non-sequential integers, addressing:
  • Security: Prevents ID enumeration attacks (e.g., /users/1, /users/2).
  • API Design: Enables opaque identifiers for public-facing APIs (e.g., /users/1535832388).
  • Compliance: Reduces PII exposure in URLs/logs (GDPR/CCPA).
• Performance: Knuth’s integer hash method ensures O(1) encoding/decoding, outperforming alternatives like Hashids (benchmarks: ~1M ops/sec).
• Deterministic & Reversible: Critical for systems requiring bidirectional mapping (e.g., caching, analytics).

Integration Feasibility

• Laravel Integration:
  • Service Provider: Minimal setup (10–15 mins) to register a singleton instance.
  • Dependency Injection: Auto-resolves Optimus in controllers/middleware.
  • Eloquent Hooks: Can encode/decode IDs in retrieved/saved events.
• Database Agnostic: Works with any SQL/NoSQL backend since it’s a pure PHP layer (no schema changes).
• API/URL Compatibility:
  • Replaces IDs in routes, API responses, and frontend state without breaking existing clients (if migration is gradual).

Technical Risk

Key Questions

1. ID Range:
   • What’s the maximum DB ID (e.g., unsignedBigInt vs. int)? Optimus defaults to 2147483647.
   • Are negative IDs or zero used? (Optimus assumes positive integers.)
2. Performance:
   • Benchmark encode/decode throughput (target: >10K ops/sec for API use).
3. Multi-Tenancy:
   • Should tenant-specific primes be used (e.g., Optimus::create($primePerTenant))?
4. Fallbacks:
   • Plan for invalid IDs in URLs (e.g., 404 vs. redirect).
5. Auditability:
   • How to log/debug original IDs if obfuscated in production?

Integration Approach

Stack Fit

• Laravel:
  • Service Provider: Register Optimus as a singleton (e.g., App\Providers\OptimusServiceProvider).
  • Middleware: Decode IDs in routes (e.g., icanhazstring/optimus-middleware).
  • Eloquent: Hook into retrieved/saved events for auto-encoding.
• Non-Laravel PHP:
  • Manual instantiation (e.g., new Optimus($prime, $inverse, $random)) in services/controllers.
• Frontend:
  • Encode IDs in API responses (e.g., return response()->json(['id' => $optimus->encode($id)])).

Migration Path

1. Phase 1: POC
   • Test encoding/decoding in staging with sample data.
   • Benchmark performance (e.g., 10K requests/sec).
2. Phase 2: Backfill
   • Add optimus_id column to DB:

     Schema::table('users', function (Blueprint $table) {
         $table->unsignedBigInteger('optimus_id')->nullable();
     });
     

   • Populate via migration:

     DB::table('users')->update([
         'optimus_id' => DB::raw('(SELECT encode(id) FROM optimus WHERE id = users.id)')
     ]);
     

3. Phase 3: API Transition
   • Update routes to decode IDs:

     Route::get('/users/{optimusId}', function ($optimusId) {
         $userId = $optimus->decode($optimusId);
         return User::find($userId);
     })->middleware('decode.optimus');
     

   • Deprecate old /users/{originalId} endpoints with redirects.

Compatibility

Sequencing

1. Generate Primes:

   php artisan optimus:spark
   

   Store primes in .env (e.g., OPTIMUS_PRIME=1580030173).
2. Add Service Provider:

   // App\Providers\OptimusServiceProvider.php
   $this->app->singleton(Optimus::class, fn() => new Optimus(
       config('optimus.prime'),
       config('optimus.inverse'),
       config('optimus.random')
   ));
   

3. Update Routes/APIs:
   • Replace {id} with {optimusId} in routes.
   • Add middleware for automatic decoding.
4. Backfill Data:
   • Run migration to populate optimus_id column.
5. Deprecate Old Endpoints:
   • Add redirects for legacy /users/{originalId} URLs.

Operational Impact

Maintenance

• Prime Management:
  • Store primes in .env or database (never hardcode).
  • Document regeneration process (e.g., php artisan optimus:spark).
• Version Updates:
  • Monitor for breaking changes (e.g., PHP 8.x deprecations).
  • Test upgrades in staging before production.
• Logging:
  • Log decoding failures (e.g., invalid IDs) for monitoring.

Support

• Debugging:
  • Original IDs can be retrieved via optimus->decode() in Tinker/debug mode.
  • Add a toOriginalId() method to models for debugging:

    public function getOriginalIdAttribute() {
        return $this->optimus->decode($this->optimus_id);
    }
    

• Client Issues:
  • Provide clear error messages for invalid IDs (e.g., "ID not found").
  • Offer a temporary fallback for legacy clients during migration.

Scaling

• Performance:
  • Singleton instance ensures zero overhead per request.
  • Benchmark under load (e.g., 10K RPS); optimize if bottlenecks exist.
• Database:
  • No impact on DB queries; obfuscation is a pre-processing step.
• Multi-Region:
  • Primes must be consistent across deployments (cache in Redis if needed).

Failure Modes

Ramp-Up

• Onboarding:
  • Documentation: Add a OPTIMUS.md to the repo with:
    • Prime generation steps.
    • Migration guide.
    • Example usage (routes, models, APIs).
  • Training: 30-minute session on:
    • How obfuscation works.
    • Debugging invalid IDs.
    • Performance implications.
• Rollout Plan:
  1. Staging: Test with 10% of traffic.