Eloquent Calamari Laravel Package

Product Decisions This Supports

• Security & Privacy: Replace predictable auto-increment IDs (e.g., ?id=1) with opaque Sqids (e.g., /link/2fC37YMkO) to mitigate ID enumeration attacks or accidental data exposure in logs/URLs.
• User Experience: Short, memorable, and shareable URLs (e.g., for marketing links, payment references, or social media) without sacrificing database integrity.
• API Design: Cleaner, more intuitive endpoints (e.g., /orders/abc123 instead of /orders/12345) that align with frontend frameworks (React, Vue) expecting "slug-like" IDs.
• Roadmap: Phase out legacy ID systems in favor of a unified obfuscation strategy across microservices or monoliths.
• Build vs. Buy: Avoid custom development of ID obfuscation logic (e.g., Base62, UUIDs) by leveraging a battle-tested, Laravel-native solution with Sqids’ collision resistance.
• Use Cases:
  • Public-facing URLs (e.g., referral links, checkout flows).
  • Audit logs or analytics where exposing raw IDs is a risk.
  • Multi-tenant systems needing tenant-agnostic ID formats.

When to Consider This Package

• Adopt if:

  • Your Laravel app uses auto-incrementing IDs exposed in URLs, APIs, or logs.
  • You need short, unique, and reversible IDs (Sqids encodes numbers into alphanumeric strings).
  • Your team prioritizes security (preventing ID guessing) or UX (cleaner URLs).
  • You’re willing to trade minimal storage overhead (Sqids IDs are ~22 chars vs. 10-digit integers) for obfuscation.
  • Your database schema supports integer primary keys (Sqids works with numeric IDs).

• Look elsewhere if:

  • You need UUIDs or GUIDs (use ramsey/uuid or Laravel’s built-in hasUuids).
  • Your IDs are non-sequential (e.g., UUIDs, strings) or require custom encoding logic.
  • You’re constrained by legacy systems that can’t handle non-integer IDs in joins/foreign keys.
  • Your app has extremely high write throughput (Sqids adds ~1ms latency per ID generation; benchmark first).
  • You need multi-model ID reuse (Sqids generates unique IDs per-model by default; configure carefully for shared IDs).

How to Pitch It (Stakeholders)

For Executives: *"This package lets us replace predictable database IDs (like /user/123) with short, random-looking codes (like /user/xY7f9P). It’s a lightweight upgrade that:

• Reduces security risks by stopping attackers from guessing user/record IDs.
• Improves UX with cleaner, shareable links (e.g., for payments or referrals).
• Saves dev time—no need to build custom ID obfuscation from scratch. Cost: Minimal (MIT license, ~50 lines of config). Risk: Low (Sqids is production-proof; we can pilot on non-critical models first."*

For Engineers: *"Eloquent Calamari integrates Sqids into Laravel’s Eloquent ORM to:

• Automatically convert Model::find(1) ↔ /model/abc123 with zero app logic changes.
• Support route model binding out of the box (e.g., Route::get('/link/{sqid}', [LinkController::class, 'show'])).
• Handle edge cases like non-canonical IDs (e.g., /link/2fC37YMkO always resolves to id=1). Setup: Add the package, configure sqids.php, and annotate models with use SqidBasedRouting. Tradeoffs: Slight storage/DB overhead (~22 chars vs. 10 digits), but negligible for most apps. Alternatives: Rolling your own Base62 or using UUIDs—but this gives us reversible, short, and secure IDs with less effort."*

For Design/UX Teams: *"Imagine URLs like app.com/checkout/abc123 instead of app.com/checkout?id=45678. This package:

• Makes links shorter and safer to share (no accidental ID leaks).
• Aligns with modern web conventions (e.g., Slack, Notion use similar patterns).
• Works seamlessly with your frontend—just update route bindings!"*