Hashids Bundle Laravel Package

Getting Started

Know what you're installing. netbull/hashids-bundle is a Symfony bundle that wires the hashids/hashids library into the Symfony DI container. As a Laravel developer, the bundle's registration, config tree, and service aliases do not apply to you — there is no HashidsServiceProvider. You have two realistic paths:

1. Laravel-native: composer require hashids/hashids (or vinkla/hashids, which is the Laravel wrapper for the same library) and bind it in a service provider. This is what most Laravel teams should do.
2. Evaluate the bundle's conventions as a reference for config shape (salt, min length, alphabet, padding) if you're porting behaviour into a Laravel config file.

If you are in a Symfony codebase (or a mixed one), the minimal steps are:

composer require netbull/hashids-bundle

• Register the bundle in config/bundles.php.
• Look first at the bundle's DependencyInjection/Configuration.php and Resources/config/services.yaml to learn the exact config key, service ID, and whether it exposes one hasher or named hashers.
• Set a salt and min_hash_length in config/packages/*.yaml, sourced from env (HASHIDS_SALT), never hard-coded.
• Clear the container cache after changing salt — Symfony compiles config into the container.

First use case: stop leaking sequential primary keys in URLs. /orders/1042 becomes /orders/jR4pQm. Inject the hasher, encode($order->getId()) when building links, decode($segment) in a controller or param converter.

Implementation Patterns

Keep the integer PK, add a public hash. Don't replace auto-increment PKs with hashes in the database. Store the bigint, expose the hash as a derived accessor / API field. This keeps indexes, foreign keys, and joins sane, and lets you rotate the salt without a data migration (at the cost of breaking old links — see Gotchas).

// encode on the way out
$payload = ['id' => $hasher->encode($order->getId())];

// decode on the way in, before route model binding
$ids = $hasher->decode($segment);           // [] on failure
abort_if(empty($ids), 404);
$order = Order::findOrFail($ids[0]);

Wrap it, don't sprinkle it. Inject hashids/hashids into a small PublicId service (encodeId, decodeId, decodeOrFail). The bundle's service is a thin adapter; your wrapper is where you enforce "decode returns exactly one positive int or throws" and where you can swap implementations later.

Composite keys are a feature. encode($tenantId, $orderId) produces a single opaque token; decode() gives you both back. This is the cleanest way to make IDs tenant-scoped in URLs without a separate lookup table — just always validate that the decoded tenant matches the authenticated user's tenant.

Multiple contexts. If the bundle only registers one hasher, or you need different salts per entity type (users vs. invoices vs. invite tokens), register additional Hashids instances manually with distinct salts/min lengths rather than reusing one global salt. One leaked salt should not de-anonymise every model at once.

API resources. Emit only the hash in id fields, and treat decode failure as a 404/422, not a 500. Laravel's Route::bind or a custom resolveRouteBinding is the natural integration point.

Config per environment. Salt from env(), min length fixed per app. Hashids config is cheap to construct, so don't cache the instance manually — let the container/singleton binding handle it.

Gotchas and Tips

• AGPL-3.0 is the headline risk. This is a strong network-copyleft licence. If you distribute or SaaS-host software that links this bundle, AGPL obligations can be read to require source disclosure. The underlying hashids/hashids library is MIT — for most commercial Laravel work, use the library (or vinkla/hashids) and avoid the bundle entirely. Verify with counsel before shipping.
• Salt changes break every existing link. There is no versioning in the hash. Rotate salt only with a planned migration/redirect strategy, or encode a short salt-version prefix in the URL path.
• decode() returns [], it does not throw. Every call site must handle the empty case. Wrap it once (decodeOrFail) and ban raw decode() in code review.
• Hashids is obfuscation, not encryption. Anyone with the salt and alphabet can reverse it. Never encode secrets, and never treat a valid decode as an authorisation check — still enforce ownership/permissions after resolving the model.
• min_hash_length is a floor, not a target. Output grows with the input number; don't assume a fixed column width or regex {n} in routes. Validate the charset instead.
• Integer-only. No UUIDs, no strings. If you're on UUID PKs you need a different approach (e.g., Sqids, which is the maintained successor to Hashids).
• Alphabet constraints. Must be ≥16 unique characters, no spaces. A typo silently degrades collision resistance; assert length/uniqueness at boot in a test.
• Zero dependents, single-digit stars. Treat it as a thin convenience wrapper with maintenance risk. Pin the version ("netbull/hashids-bundle": "1.*"), and be prepared to inline the ~50 lines of DI config it saves you.
• Debugging: in Symfony, debug:container | grep -i hashid to confirm the service ID; in a plain Laravel test, dump($hasher->encode(123)) and round-trip decode in a unit test with the production salt to catch config drift early.