Hashids Laravel Package

Product Decisions This Supports

• Public API ID format as a product contract. Committing to opaque string resource IDs instead of sequential integers affects URLs, docs, SDKs, support workflows, analytics, caching, and partner integrations. It is a one-way door: cheap before public launch, expensive after clients bind to numeric or encoded IDs.
• Enumeration risk posture. Supports a deliberate decision about how much the business cares that sequential IDs reveal record counts, growth rates, and allow catalog walking. This package raises the cost of casual enumeration only; it is obfuscation, not authorization or security.
• Build vs. buy vs. vendor. Lets the product keep fast integer primary keys internally while presenting opaque IDs externally, avoiding a larger UUID/ULID primary-key migration when the only driver is public presentation. The real choice is depend on a tiny adapter, vendor/inline it, or keep integers.
• Framework consolidation. Only meaningful if the roadmap already commits to laravel-json-api as the API layer. Adopting it reinforces JSON:API compliance as a deliberate standard rather than ad-hoc REST style.
• Roadmap timing. Decide before public launch or inside an existing API version boundary. Salt, length, or alphabet changes later are breaking API events requiring versioning, deprecation, and client migration.
• Use cases unlocked: shareable public links, customer-facing IDs in support workflows, multi-tenant APIs where ID space should not be inferable, partner/marketing surfaces where “user #3” is unacceptable.
• Not a fit for: authorization, PII protection, non-reversible identifiers, or multi-service ID minting without centralized salt ownership.

When to Consider This Package

• Consider it when you are already on laravel-json-api, need spec-compliant opaque string resource IDs quickly, want to retain integer primary keys for performance, and the threat model is casual enumeration or competitive intelligence rather than determined adversaries.
• Adoption criteria: salt stored in a secrets manager, minimum ID length configured and documented, encoder registered once at the framework boundary, API contract explicitly states IDs are opaque and non-parseable, test coverage for resource IDs and relationship identifiers, and a compatibility spike across PHP, Laravel, laravel-json-api, and the underlying Hashids library.
• Look elsewhere or build in-house when you are not on laravel-json-api; you need genuine unguessability or non-reversibility; salt rotation or per-tenant/per-environment isolation is a hard requirement; supply-chain policy blocks tiny dependencies; multiple services must independently resolve the same public ID; or your API surface is mixed and only one surface would use the encoder.
• Dependency posture: with 5 stars and 0 dependents, treat this as source to adopt, not a library to rely on. The adapter is small enough to vendor or inline, which removes the bus-factor concern.

How to Pitch It (Stakeholders)

Executives: This is a small configuration decision that stops our public API from advertising how many customers, orders, or records we have, and prevents casual walking of our data by incrementing URLs. It keeps database performance intact with integer keys internally while presenting opaque IDs externally, and it aligns with the JSON:API standard if we have adopted it. The important timing point is that changing ID formats after launch breaks clients, links, caches, and integrations, so it is materially cheaper to decide before public launch. Recommendation: adopt only if laravel-json-api is already committed, and vendor the tiny adapter rather than treating a five-star, zero-dependent package as strategic infrastructure. Position it as anti-enumeration and obfuscation, not security or authorization.

Engineering: Register the encoder at the laravel-json-api boundary, keep the salt in the secrets manager, pin minimum length in config, and document IDs as opaque strings in the API contract. Test encoding and decoding across resource objects, relationship identifiers, relationship endpoints, create/update responses, pagination links, and error documents. Verify behavior under config:cache, route model binding, authorization policies, caches, logs, exports, and support tooling. Pilot one low-risk resource first, then expand only after frontend, cache, analytics, and support impacts are owned. Treat salt rotation as a versioned API event, not a config change, and name an owner for the vendored source. If non-reversible or distributed IDs become a requirement later, the migration path is UUIDv7/ULID — which is exactly why this ID-format decision should be made deliberately now.