Laravel Nova Hashids Laravel Package

Technical Evaluation

Architecture fit

• The package is a Laravel Nova 5 card plus a small card-scoped HTTP API for Hashids encode/decode, backed by vinkla/hashids. It fits Nova’s extension model and does not require a separate service, database schema, or queue.
• Version 3.0.0 adds a Converter contract, which is the most strategically useful change: teams can bind a custom hash algorithm without forking the package. This improves fit for organizations with existing salt/hashid conventions.
• Fit is binary: the package is only viable on Nova 5, Laravel 12 or 13, PHP 8.2+, and vinkla/hashids 13 or 14. There is no graceful coexistence with Nova 3 or 4.

Integration feasibility

• Installation is a normal Composer dependency; no migrations are mentioned. The real effort is the surrounding platform upgrade to Laravel 12/13 and Nova 5.
• The card API changed (selected becomes connection, response fields changed), but release notes state only the card consumes it. Blast radius is low unless custom callers were built against the v2 endpoints.
• Route caching must be refreshed after upgrade (php artisan route:cache), which is an easy operational miss.

Technical risk

• The dominant risk is security, not functionality. With v2 on Nova 4 or 5, the card routes did not authenticate users because Nova’s nova middleware group no longer authenticates. A guest could list connections and encode/decode IDs. If the current environment is v2 on Nova 4/5, treat this as an active security finding and mitigate immediately—upgrade, restrict routes, or disable the card until remediated.
• Version lock is strict: Composer will not install v3 alongside Nova 3 or 4, so this cannot be rolled out incrementally across mixed Nova versions.
• The 3.0.0 fix list touches meaningful edge cases—invalid hashids returning HTTP 500, multi-number hashids, connection-name validation, large model IDs, leading zeros/GMP octal parsing, and bad connection configuration. These are positive changes but warrant regression testing against real data.
• Vue 2 removal and the Vue 3/Laravel Mix 6 rebuild are expected for Nova 5; custom front-end extensions against the v2 card will break.

Key questions

• Are we already on Nova 5, Laravel 12/13, PHP 8.2+, and vinkla/hashids 13/14?
• Do we currently run v2 on Nova 4/5? If yes, who owns immediate containment of the unauthenticated card routes?
• Do any internal tools or scripts call the card API directly, beyond the shipped Vue card?
• Do we depend on GMP, very large model IDs, or leading-zero IDs that the release explicitly fixes?
• Is route caching enabled in production, and is there a deployment step to rebuild it?
• Do we need a custom Converter, or is the default Hashids behavior sufficient?
• Are there other packages pinning vinkla/hashids below version 13?

Integration Approach

Stack fit

• Adopt only as part of a Nova 5 / Laravel 12–13 / PHP 8.2+ platform baseline. This package should be treated as a downstream dependency of that upgrade, not as the driver.
• The card is admin-facing and low-traffic; it has no runtime dependency on customer-facing request paths.

Migration path

1. Upgrade the application to Laravel 12 or 13 and Laravel Nova 5.
2. Require pmochine/laravel-nova-hashids:^3.0.
3. Remove any array_has() helper added as a workaround for issue #2.
4. Run php artisan route:cache if routes are cached.
5. Verify that only users passing Nova’s viewNova gate can access the card, and test guest and non-authorized access explicitly.
6. Smoke-test encode/decode, default connection display, invalid hashid handling, multi-number rejection, large IDs, leading zeros, resource-detail auto-conversion, Enter-to-convert, and the Copy hashid button.
7. Promote staging to production with a rollback plan.

Compatibility

• No coexistence with Nova 3 or 4; Composer enforces the break.
• Requires vinkla/hashids 13 or 14. Audit transitive dependency constraints before upgrading.
• Vue 2 components and Sass are removed; any local customization layered on the v2 card must be rebuilt or retired.
• The API rename is card-internal, but confirm no custom consumers exist before assuming zero impact.

Sequencing

• If currently exposed on v2 with Nova 4/5, sequence security containment first, then the platform upgrade, then the package upgrade.
• Do not bundle the package major bump into an unrelated release; coordinate with the Nova upgrade owner and schedule a dedicated regression pass.
• After deployment, re-run route caching and authorization checks as part of the release checklist, not as an afterthought.

Operational Impact

Maintenance

• The package has a small surface area but follows Nova’s major-version cadence. Expect repeated breaking upgrades when Nova makes similar middleware or front-end changes. Budget for periodic major-version work.
• The addition of PHPUnit tests, Vitest tests, and a GitHub Actions workflow is a positive maintainability signal, though the project remains a small, likely single-maintainer dependency. Pin versions and monitor releases.

Support

• Inline error messages, preserved field usability after errors, and German translations should reduce admin support tickets.
• Invalid hashids and bad connection configuration now degrade gracefully instead of returning HTTP 500, which lowers operational noise.
• Support teams should know that card access is now gated by viewNova; users who previously reached the card without Nova access will lose it.

Scaling

• Scaling risk is low: the card is an admin tool, and conversion is local Hashids work rather than a shared service.
• A custom Converter implementation should be stateless per request and reviewed for performance if it introduces external calls.

Failure modes

• Misconfigured connection: card shows a warning and Laravel reports the exception; no server error.
• Invalid or multi-number hashid: user-facing message; only single model IDs are supported.
• Stale route cache after upgrade: card endpoints may misbehave until route:cache is rerun.
• Authorization regression: if middleware is customized or bypassed, the v2 exposure pattern could return. Keep guest-access tests in the regression suite.
• Large-ID and leading-zero parsing issues are fixed, but verify if those edge cases exist in production data.

Ramp-up

• Developer ramp-up is low for teams already familiar with Nova: no migrations, a self-contained card, and straightforward UX. The custom Converter contract adds modest implementation effort.
• Operations ramp-up is mostly procedural: route-cache refresh, authorization smoke tests, and a rollback path. Note that remaining on v2 with Nova 5 is not a safe long-term fallback because of the authentication gap.