Weave Code
Hashids Laravel Package
laravel-json-api/hashids
Adds Hashids support to Laravel JSON:API, encoding resource IDs into short, obfuscated strings and decoding them on request. Configure salt, length, and alphabet while keeping numeric database keys hidden behind spec-compliant JSON:API routes and relationships.
Encode model IDs to JSON:API resource IDs.
Frequently asked questions about Hashids
- How do I install laravel-json-api/hashids in Laravel?
- Install it with Composer as laravel-json-api/hashids, then publish the package config file and register the service provider as described in the repository. After that, wire the Hashids encoder into your JSON:API server, either globally or per resource schema. Installation is mechanically small; the larger effort is verifying that every endpoint returns and accepts the hashed IDs correctly.
- Do I need Laravel JSON:API installed to use this package?
- Yes. The package is an adapter for laravel-json-api's resource-ID encoder contract, so it has no delivery value unless your application already uses Laravel JSON:API as its API layer. Treat whether you are a JSON:API shop as the gating decision before evaluating whether you want hashed IDs.
- Does laravel-json-api/hashids work with relationships, includes and filters?
- Yes. IDs are encoded on the way out and decoded on the way in, so resource objects, relationship identifiers, relationship endpoints, included resources, route bindings and filters all resolve the hashed identifiers transparently. You should still verify each of those surfaces in your own test suite.
- Is Hashids a security feature or encryption?
- No. Hashids is reversible obfuscation, not encryption or a security control; the salt is the entire secret. It hides sequential database keys from casual enumeration, but anyone with the salt and algorithm can decode an ID. Do not let planning or review documents describe it as protecting data or enforcing authorization.
- How do I configure the Hashids salt, minimum length and alphabet?
- Publish the package config file and set the salt, minimum length and alphabet there. The package supports global configuration and per-resource encoder configuration, so you can tune behavior for individual schemas. Choose the salt carefully and store it as a secret, because it determines whether your public IDs can be decoded.
- Can I use different Hashids encoders per resource?
- Yes. The package supports per-resource or global encoder configuration, so different JSON:API resource types can use different Hashids settings if needed. In most applications a single global encoder with a strong salt is simpler and easier to reason about. Document any per-resource differences because they become part of your public API contract.
- What breaks if I change the salt or minimum ID length later?
- Changing the salt, minimum length or alphabet changes the public IDs clients see, which is a breaking API change once IDs are in bookmarks, shared links, caches, logs or partner integrations. Treat such a change as a versioned API event with deprecation and client migration, not a routine config tweak. It is much cheaper to settle these settings before public launch.
- How do I test hashed IDs across my JSON:API endpoints?
- Scope testing as a finite but explicit matrix rather than assuming correctness. Cover resource objects, relationship identifiers, relationship endpoints, create and update responses, pagination links and error documents. Confirm that numeric database keys never leak and that every route binding decodes the hashed ID as expected.
- Is laravel-json-api/hashids safe to depend on in production?
- Be cautious: the package has a small ecosystem footprint, a single maintainer and few dependents, so treat it as source you adopt rather than a strategic library you rely on. The adapter is small enough that vendoring or inlining it is a defensible option, and you should name an engineer who owns that fork if upstream goes quiet. Also close the PHP, Laravel, laravel-json-api and hashids version matrix with a timeboxed spike before committing.
- What are alternatives to Hashids for obfuscating resource IDs?
- Alternatives include using UUIDs or ULIDs as public resource keys, writing your own encoder against laravel-json-api's resource-ID contract, or keeping numeric IDs if opacity is not a real requirement. Hashids is a fit when you want short, non-sequential public IDs while retaining integer primary keys internally for index size and write performance. If you need per-tenant or per-environment salt rotation, reversible encoding may be the wrong choice.
Weaver
How can I help you explore Laravel packages today?