Hashids Bundle Laravel Package

Product Decisions This Supports

• Opaque identifier strategy for public-facing URLs — decide whether user-facing routes expose sequential database IDs (/orders/1042) or non-guessable hashed tokens (/orders/Xk9bQ2). This package is the Symfony-native implementation of that decision, converting route parameters on the fly so controllers keep working with integer IDs internally.
• Security posture: enumeration & scraping resistance — choosing to obscure IDs raises the cost of sequential enumeration and bulk scraping attacks; relevant to roadmap items around privacy, tenant isolation, and public API surface hardening.
• Build vs. buy for ID obfuscation — avoids building bespoke encode/decode middleware, salt management, and route-parameter resolvers in-house; a small, single-purpose dependency vs. ~1–2 dev-weeks of custom plumbing plus ongoing maintenance.
• Use cases: public shareable links (invites, invoices, receipts), multi-tenant resource addressing, deep-link and email URLs where exposing record counts or creation order is undesirable, migration of legacy integer IDs to opaque handles without schema changes.
• Framework upgrade decisions — v4.0.0 hard-requires Symfony 6.2+ and moves to the ValueResolver mechanism (replacing the legacy param-converter path). This directly gates your Symfony 6.x/7.x upgrade plan: adopting v4 means committing to Symfony 6.2+ and PHP 8.1+, and auditing any existing @ParamConverter-style annotations in your routes.
• Dependency footprint & upgrade cost — a narrow, well-scoped bundle is low-risk to adopt, but its major-version cadence mirrors Symfony's own; treat it as a maintenance line item tied to Symfony upgrade windows rather than an independent roadmap item.

When to Consider This Package

Adopt when:

• You are on Symfony 6.2+ / PHP 8.1+ and want ValueResolver-native conversion (v4.0.0), or on Symfony 5.4/6.0–6.1 and can stay on v3.1.0.
• You need route-parameter conversion specifically — i.e., IDs appearing in paths/query strings — rather than a generic hashing utility.
• Your IDs are integers or short strings and you want reversible, salt-based obfuscation (not encryption, not a random UUID replacement).
• You want a maintained, minimal wrapper around hashids/hashids rather than owning the wiring, DI configuration, and per-route resolver plumbing.
• You need a consistent salt strategy across environments configured through bundle config/YAML.

Look elsewhere when:

• You need cryptographic guarantees — Hashids is obfuscation, not security. For tokens that grant access, use signed URLs, ULIDs/UUIDv7, or a secrets manager.
• You can simply switch the primary key to a UUID/ULID — that changes the data model but removes the encode/decode layer, salt management, and this dependency entirely. Often the cleaner long-term call for greenfield.
• Your IDs are consumed by external systems or analytics that require stable, human-readable identifiers — hashed IDs leak into logs, dashboards, and support tickets and hurt debuggability.
• You are on Symfony < 6.2 and unwilling to upgrade — v4.0.0 is not for you; pin v3.1.0 and note it as technical debt.
• You need search-engine-friendly slugs (readable words) rather than opaque tokens — that is a different problem and a different package.

How to Pitch It (Stakeholders)

For executives (one paragraph): We recommend adopting roukmoute/hashids-bundle to stop exposing sequential database IDs in public URLs. It is a small, focused Symfony integration of a mature hashing library that converts IDs on the way in and out of routes, so no data-model change is required and internal code keeps using plain integers. The business outcome is reduced link-guessing and scraping exposure on shareable links, invitations, and receipts, at the cost of one lightweight dependency. Note the new v4.0.0 requires Symfony 6.2+ and PHP 8.1+, so this lands as part of our platform upgrade rather than as a standalone change.

For engineering:

• v4.0.0 is a breaking release: it migrates from the legacy route/param-converter approach to Symfony's ValueResolver (6.2+). Dropping it in means auditing routes for @ParamConverter/sensio-style annotations and any HashidsConverter usages, and confirming framework.value_resolvers wiring (tagged services auto-register by default).
• Minimum versions move to Symfony 6.2 / PHP 8.1. Anything older must remain on v3.1.0, which should be logged as tech debt with a sunset date tied to the Symfony upgrade.
• Configuration is DI-driven: a single salt, min-length, and alphabet per environment. Rotate salts deliberately — changing the salt invalidates every previously shared link, so treat it like a key-rotation event with a migration/redirect plan.
• Semantics to document explicitly: Hashids is reversible obfuscation, not security. It must not be the sole authorization check on any resource; pair it with policy/ownership checks as usual.
• Operational caveat: hashed IDs will appear in logs, error reports, and support conversations. Ensure decode helpers are exposed to support tooling, or expect friction in incident triage.
• Recommended rollout: adopt on new public-facing routes first (share links, invitations), measure, then retrofit existing routes; keep the salt config centralized and environment-scoped.