Filament Hashids Laravel Package

Technical Evaluation

Architecture fit swindon/filament-hashids is a thin Filament plugin that wraps the Hashids library to obfuscate sequential primary keys in Filament resource URLs (e.g. /admin/orders/1 → /admin/orders/jR4bQ2). It sits in the presentation/routing layer only — it does not alter schema, storage, or domain logic. That makes it a low-blast-radius addition: it can be adopted on one panel or one resource at a time, and removed without data migration. For a TPM the relevant framing is that this is a cosmetic/hygiene control, not an access-control control. It reduces casual ID enumeration and improves perceived URL quality; it does not replace authorization policies, and should not be sold internally as a security feature.

Integration feasibility High. The package targets the standard Filament + Laravel stack we already run; adoption is expected to be composer install, plugin registration in the panel provider, a published config file holding the salt and minimum hash length, and per-resource opt-in. Expect roughly 1–3 developer-days including regression testing of resource routes, relation-manager links, and any action that generates URLs. The main unknown is whether it hooks route-key generation globally per panel or per resource — that determines whether the change is contained or panel-wide.

Technical risk

• Salt lifecycle is the dominant risk. Hashids is reversible obfuscation, not encryption. Rotating the salt silently invalidates every previously issued admin URL — bookmarked links, saved filters, links pasted into tickets and chat all 404 at once. Salt must be treated as a managed secret with a documented change procedure.
• Cross-model collisions. If a single global salt is used, the same integer encodes to the same string across models. If resolution is not scoped to the expected model, an encoded ID from one resource can resolve against another. This is the one issue that would push me to require engineering sign-off before rollout.
• Ecosystem coupling. The plugin's compatibility is bounded by Filament's major-version cadence. A Filament v4 upgrade will likely gate our ability to upgrade the panel until the plugin follows.
• Thin release signal. v1.0.0 is published with no changelog content beyond a commit-range link. We cannot infer scope, fixes, or known issues from the release itself; the assessment below relies on package intent and repository inspection rather than release documentation.
• Maturity/bus-factor. Single-maintainer package at a first stable tag. Semver commitment from v1.0.0 is a positive signal but not evidence of longevity.

Key questions

1. Does the plugin scope hash resolution per model, or is the salt global across resources?
2. Is the salt read from config() (cache-safe) or env() at request time (breaks under config:cache)?
3. What is the fallback when a decode fails — 404, or silent fallback to raw ID? A raw-ID fallback would defeat the purpose.
4. Does it interact safely with soft deletes, global scopes, and policy checks that call resolveRouteBinding?
5. What is the maintainer's stated Filament version support matrix and release cadence?
6. Are relation-manager and nested-resource URLs covered, or only top-level resource routes?

Integration Approach

Stack fit Native fit. No new infrastructure, no queue, no external service, no PHP extension requirements beyond what Hashids itself needs. Configuration is a single published file plus environment variables. No conflicts anticipated with our existing Filament plugins unless another plugin already overrides route-key resolution on the same resources — that overlap should be checked before install.

Migration path Non-destructive and reversible. There is no data migration: primary keys stay as they are, only their URL representation changes. Recommended path:

1. Install and register the plugin with the feature disabled by default.
2. Enable on a single low-traffic internal resource in staging; verify list/edit/view/relation URLs and all generated action links.
3. Enable panel-wide in staging; run the existing admin smoke-test suite.
4. Roll to production with the plugin enabled but per-resource opt-in, expanding coverage over one or two sprints.
5. Keep the disable flag documented so rollback is a config change, not a deploy.

Compatibility Confirm Filament major version support before committing, and pin the plugin version alongside our Filament version so upgrades are deliberate. Laravel-side compatibility is likely broad, but config:cache behaviour and PHP version floor should be verified in CI rather than assumed.

Sequencing Do this after any in-flight Filament upgrade, not before — otherwise we inherit a plugin compatibility blocker on top of a framework migration. Sequence: Filament version lock → plugin install (disabled) → single-resource pilot → panel-wide rollout → salt-management runbook → documentation for support staff. The runbook matters more than the code; it should be written before panel-wide enablement, not after.

Operational Impact

Maintenance Low ongoing code maintenance; the real cost is version-tracking Filament releases and validating the plugin against each. Budget a small recurring allowance per Filament upgrade cycle rather than a large one-off. Single-maintainer dependency means we should be willing to vendor a fork if the package stalls — the code surface is small enough that this is realistic, which materially lowers the risk.

Support Support burden is concentrated in one scenario: "my saved link stopped working." Tier-1 staff need to know that encoded URLs are non-portable across environments (staging salt ≠ production salt, by design) and non-portable across salt rotations. Without that, expect misrouted tickets to engineering. Add a short knowledge-base entry at rollout.

Scaling Effectively free. Encoding and decoding are constant-time string operations against a short integer; the database still receives a primary-key lookup, so query plans and index usage are unchanged. No measurable impact on request latency or database load at our volumes. The only scaling consideration is human: more resources under the plugin means more surface to re-verify on each Filament upgrade.

Failure modes

• Salt rotation / environment mismatch → blanket 404s on admin resource URLs. Highest-impact, most likely failure; mitigated by runbook and by never rotating without a comms plan.
• config:cache with env-based salt → decode failures in production only, invisible in local dev. Test explicitly in a cached-config environment.
• Cross-model resolution → wrong record loaded for a valid-looking hash. Rare but severe; requires the scoping question above to be answered before rollout.
• Filament upgrade without plugin support → panel routes break at deploy time. Mitigated by pinning and staging the upgrade.
• Plugin abandonment → no immediate failure, but eventual incompatibility with Filament majors. Mitigated by the small code surface and fork option.

Ramp-up Low. A Laravel-fluent developer unfamiliar with the package should be productive within half a day; the concepts (route keys, Hashids, Filament plugin registration) are all standard. Plan a short walkthrough for the team plus the support KB entry, and treat the salt-management procedure as the only piece requiring deliberate training rather than discovery learning.