Eloquent Calamari Laravel Package

Technical Evaluation

Architecture Fit

• Use Case Alignment: Ideal for systems requiring user-friendly, non-sequential IDs (e.g., URLs, APIs, or public-facing identifiers) while preserving internal auto-incrementing IDs for performance and database integrity.
• Laravel/Eloquent Native: Leverages Laravel’s Eloquent ORM, minimizing architectural disruption. Works transparently with existing Model::find() logic.
• Decoupled from Business Logic: Sqids generation/decoding is abstracted, allowing adoption without modifying core domain models.

Integration Feasibility

• Low Friction: Single Composer dependency with minimal configuration (e.g., SqidBasedRouting middleware for route binding).
• Database Agnostic: No schema changes required; operates at the application layer.
• Optional Features: Route model binding and non-canonical ID handling are opt-in, reducing mandatory refactoring.

Technical Risk

• Performance Overhead: Sqids generation/decoding adds minimal latency (~1–5ms per request, depending on ID length/complexity). Benchmark in production-like conditions.
• ID Collisions: Theoretically possible if models share the same Sqids alphabet/length. Mitigate via per-model configuration (e.g., sqid() method overrides).
• Route Binding Complexity: Custom route model binding may require adjustments to existing API routes or URL structures.
• Migration Impact: Existing URLs/IDs must be mapped during transition (e.g., via a sqid() method or middleware).

Key Questions

1. ID Length/Alphabet: Will default Sqids (e.g., 2fC37YMkO) conflict with existing URL conventions or security requirements?
2. Backward Compatibility: How will legacy systems (e.g., third-party integrations) handle mixed ID formats during migration?
3. Caching Strategy: Should Sqids be cached (e.g., Redis) to reduce generation overhead for high-traffic models?
4. Auditability: How will internal systems (e.g., logs, analytics) reference obfuscated IDs vs. raw DB IDs?
5. Testing Scope: Does the team need to validate edge cases (e.g., ID 0, negative IDs, or custom primary keys)?

Integration Approach

Stack Fit

• PHP/Laravel: Native support; no polyfills or wrappers needed.
• Database: Compatible with all SQL databases (MySQL, PostgreSQL, SQLite) using auto-incrementing integers.
• Frontend/Backend: Works seamlessly with Laravel’s routing, API responses, and Blade templates.
• Microservices: Can be adopted incrementally per service (e.g., API layer first, then frontend).

Migration Path

1. Phase 1: Proof of Concept
   • Install package and test basic Sqids generation/decoding in a staging environment.
   • Validate performance impact with load tests (e.g., 10k RPS).
2. Phase 2: Model-Level Adoption
   • Add use RossBearman\EloquentCalamari\HasSqid; to target models.
   • Override sqid() method if customization is needed (e.g., per-model alphabets).
3. Phase 3: Route Integration
   • Apply SqidBasedRouting middleware to API routes.
   • Update frontend/backend URL generation to use route() helpers with Sqid-based parameters.
4. Phase 4: Legacy Support
   • Implement middleware to handle mixed ID formats during transition (e.g., fallback to raw IDs if Sqid fails).
   • Deprecate old IDs via feature flags or redirects.

Compatibility

• Laravel Versions: Tested with Laravel 10+ (check composer.json constraints).
• Eloquent Extensions: May conflict with custom find() logic or global scopes. Test with existing packages (e.g., spatie/laravel-activitylog).
• Caching Layers: Ensure Sqids are not cached aggressively (e.g., Varnish) if dynamic generation is needed.

Sequencing

• Critical Path: Prioritize models exposed to users (e.g., User, Product) over internal models.
• Dependencies: Integrate Sqid-based routing after core models are obfuscated.
• Rollback Plan: Maintain a raw_id() accessor or database view for emergency fallback.

Operational Impact

Maintenance

• Dependency Updates: Monitor rossbearman/eloquent-calamari and sqids PHP package for breaking changes.
• Configuration Drift: Document per-model Sqid settings (e.g., alphabet, length) to avoid inconsistencies.
• Debugging: Add logging for Sqid generation failures (e.g., invalid IDs, collisions).

Support

• Developer Onboarding: Requires familiarity with Laravel’s service providers and middleware. Document:
  • How to generate/read Sqids manually (e.g., Model::sqid()).
  • Troubleshooting route binding issues.
• End-User Impact: Minimal if URLs are backward-compatible. Communicate changes to public APIs.

Scaling

• Horizontal Scaling: Stateless Sqid generation scales automatically; no shared state.
• Database Load: No additional queries; generation is in-memory.
• Cold Starts: Irrelevant for PHP/Laravel (unlike serverless).

Failure Modes

Ramp-Up

• Training: 1–2 hours for developers to understand Sqids, route binding, and migration steps.
• Testing: Allocate time for:
  • Unit tests for Sqid generation/decoding.
  • Integration tests for route binding.
  • Load tests to validate performance.
• Rollout Strategy:
  • Canary: Deploy to 10% of traffic first (e.g., via feature flag).
  • Monitor: Track errors (e.g., SqidNotFoundException) and latency spikes.
  • Feedback Loop: Gather input from frontend teams on URL readability.