Filament Sqids Laravel Package

Technical Evaluation

Architecture fit — korfra/filament-sqids is a thin adapter that swaps Filament's default numeric route keys for Sqids — short, obfuscated, reversible strings generated from integers. Architecturally it sits at the routing/serialization boundary: models expose a Sqid as getRouteKey(), Filament resource URLs render it, and inbound requests are decoded back to the primary key before binding. It does not touch persistence, so it stays out of the domain layer — which is the right shape for a presentation concern. The trade-off is that URL identity becomes a derived value, so every surface that constructs or consumes a Filament URL (tables, relation managers, notifications, exports, emails, embedded links) becomes an implicit dependency on that derivation.

Integration feasibility — Low effort. Composer install, optional config publish (alphabet, minimum length, blocklist), and a trait/interface on the models whose IDs you want obfuscated. No migrations, no schema change, no data backfill. A Laravel developer can spike this in under a day.

Technical risk — Three items dominate:

1. Pre-1.0 churn. This is 0.0.1 → 0.1.0, a pre-release minor bump. Under semver, 0.x makes no stability promise; any 0.2.0 may break config keys or trait signatures. Treat the API as unstable and pin exactly.
2. Not a security control. Sqids are reversible by design — anyone with the alphabet and minimum length can enumerate your ID space. If the motivation is "hide how many orders we have," that works; if the motivation is authorization, it does not. Access control must remain in policies.
3. URL permanence. Sqids are deterministic given an alphabet + min length. Changing either config value silently rotates every URL in the system — bookmarked links, shared deep links, webhook callbacks, email CTAs, and anything an external partner stored. This is the highest-severity operational footgun and needs an explicit "config is frozen" policy.

Secondary risks: coverage gaps (does it handle nested/relation-manager routes, global search results, and Filament's own generated links consistently?), interaction with any other package that overrides route keys, and cache/CDN layers keyed on the raw path.

Key questions

• The v0.1.0 release notes are a bare changelog link with no described changes. What actually changed between 0.0.1 and v0.1.0? Read the diff before adopting — a 0.x minor can be a rewrite.
• Which Filament version(s) are supported — v3 only, or v4? Is the maintainer tracking Filament's release cadence?
• Does it decode on inbound binding (404 on malformed input) or pass through raw strings to the query?
• Is there a documented migration story for existing numeric URLs (redirect layer)?
• Test coverage and CI status; is behavior pinned by a test suite we can trust as a contract?
• Bus factor: single maintainer? Is the package small enough that forking is a realistic fallback?

Integration Approach

Stack fit — Requires a modern Laravel (10/11) + PHP 8.1+ stack with Filament. If we're still on an older Filament minor or a PHP version below that floor, this is blocked outright — verify first, before any design work.

Migration path — Do not touch primary keys. Introduce sqids as a rendering concern only: keep integer PKs internally and in the database, apply the route-key trait per model, and roll out resource-by-resource rather than panel-wide.

Suggested path:

1. Spike (1–2 days). Install into a sandbox, apply to one low-traffic resource, and exercise the full surface: list/create/edit URLs, relation managers, global search results, table actions, and any notification or email that deep-links into the panel.
2. Freeze config. Lock alphabet and minimum length in a config file committed to the repo, with a comment stating it must never change without a URL-migration plan.
3. Redirect shim. If numeric URLs were previously public or shared, add a middleware that 301s /admin/orders/123 to the sqid form. Cheap insurance, removes the "old links are dead" support load.
4. Widen. Apply to remaining models once the contract tests are green.

Compatibility — Check for collisions with HasUuids/HasUlids, any custom resolveRouteBinding, and any place we hand-build Filament URLs by string concatenation. Audit caching: if we cache responses or pages by path, sqid URLs still cache fine, but cache-invalidation logic that assumes numeric segments needs review.

Sequencing — Pin 0.1.0 exactly in composer.json and hold off on composer update for this package until each new tag's diff has been reviewed. Pair adoption with contract tests asserting URL shape and round-trip decode, so any future 0.x breakage fails CI rather than production. Land this in a maintenance window, independent of other Filament upgrades — don't stack two risky changes in one deploy.

Operational Impact

Maintenance — Small, single-maintainer package with a narrow surface area. Upside: low LOC means a fork is genuinely viable if the maintainer goes dark. Downside: no roadmap guarantee and no deprecation policy. Mitigation is to wrap usage behind our own trait or interface so the third-party dependency can be swapped for a hand-rolled implementation without touching every model.

Support — No commercial support; community issues only. On the plus side, the underlying Sqids algorithm is a stable, well-specified standard with library implementations in many languages, so the concept is safe even if this specific wrapper stalls.

Scaling — Negligible runtime cost — integer-to-string encoding per URL render, no additional queries and no schema change if the sqid is computed on the fly. Two things to watch: (a) sqid length grows with ID magnitude once IDs exceed the minimum-length floor, so very large tables yield longer URLs; (b) if anyone is tempted to add a persisted sqid column for indexing, that's a real storage and migration cost — resist it.

Failure modes

Ramp-up — Low. A Laravel developer is productive with it in half a day; the real cost is the team-wide conceptual correction that obfuscated IDs aren't secret. Add a line to onboarding docs and a code comment on the trait. Budget roughly one sprint-week end-to-end including spike, redirect shim, and contract tests.

Recommendation — Worth adopting for URL cosmetics if the driver is "don't expose sequential IDs," and only after the 0.0.1→0.1.0 diff is reviewed and the Filament version floor is confirmed. Pin exactly, freeze the config, and keep authorization in policies where it belongs.