- How do I install mtvs/eloquent-hashids in a Laravel app?
- Install it with Composer using composer require mtvs/eloquent-hashids, then publish any package config if you need to customize the salt, alphabet, or minimum hashid length. Laravel's package auto-discovery registers the service provider, so no manual registration is normally required. After publishing, clear or rebuild your config cache so the new settings take effect. Check the repository's composer.json for the supported Laravel and PHP constraints before installing in an older project.
- How do I add a hashid to an Eloquent model?
- Add the HasHashid trait to the model you want to expose, and the package computes a hashid attribute on the fly from the integer primary key. No database column, migration, or backfill is required because the value is derived at runtime. Your existing integer keys and foreign keys stay exactly as they are. Because it is an accessor, remember to append the attribute or expose it through an API Resource if you need it in JSON output.
- Can I query Eloquent models by hashid instead of ID?
- Yes, the trait lets you resolve models by hashid, typically by decoding the hash back to the integer key and querying on the primary key. That decode-then-query approach is also the recommended pattern for performance, since there is no database index on a computed hashid. Malformed or tampered hashes should be handled explicitly so they return a 404 rather than an exception. Always validate the hash format before passing it to a query.
- Does mtvs/eloquent-hashids work with Laravel route model binding?
- Yes, the package is designed to support route model binding so URLs can contain hashids while the database keeps integer keys. You typically override getRouteKeyName or resolveRouteBinding on the model to decode the hashid and look up the record by its primary key. Invalid or unknown hashes should fall through to a 404 response rather than a 500. Test binding on each model you expose, including nested and polymorphic routes, since those are common sources of leaks.
- Which Laravel and PHP versions does mtvs/eloquent-hashids support?
- Compatibility depends on the package release and its underlying Hashids dependency, so verify the constraints on Packagist and in the repository's composer.json against your Laravel and PHP matrix. Because the package is a thin wrapper around Eloquent, most breakage comes from major Laravel upgrades rather than from the hash logic itself. Pin the version in composer.json and run your route binding and serialization tests after every upgrade. If the package lags behind a new Laravel release, wrapping it in your own application-level trait or adapter limits the blast radius.
- Is Hashids secure enough to hide database IDs?
- Hashids is reversible obfuscation, not encryption, and anyone who knows the salt and alphabet can recover the original integer IDs. Use it to make URLs cleaner and less enumerable by casual users, not as an authorization or access-control mechanism. Never treat a valid hashid as proof that the caller is allowed to see that record, and keep your salt in secrets management rather than in code. If you need identifiers that cannot be reversed, choose UUIDs or ULIDs instead.
- What happens to existing URLs if I rotate the hashid salt?
- Changing the salt produces entirely different hashids for the same integer IDs, so any previously shared or indexed URLs will stop resolving. That makes salt rotation a breaking change you should plan and communicate, ideally with redirects or a temporary dual resolver. Rotating is still worth doing if a salt leaks, but treat it as an incident response step with a documented runbook. Keep the salt consistent across all environments that share links, and include it in config caching considerations.
- How do I stop invalid hashids from causing 500 errors?
- Guard every decode at your application boundary, since malformed input can throw instead of returning null depending on how you call the package. Wrap the decode in a check and return a 404 or a validation error when the hash is not valid or does not resolve to a record. Add feature tests for empty strings, truncated hashes, and hashes from a different salt. Also monitor 404 and 500 rates after rollout so a bad link pattern is caught quickly.
- Does using hashids hurt performance on large collections?
- CPU cost is negligible for normal single-record requests because generating a hashid is a fast, local computation with no database round trip. The real concern is serializing large collections or hot endpoints where a hashid is computed for every model on every request. Cache computed values or avoid appending the attribute on bulk endpoints where it is not needed. Keep lookups keyed on the integer primary key so you never lose index performance.
- Should I use hashids or UUIDs and ULIDs for public IDs?
- Choose hashids when you want short, readable URLs and are happy with reversible obfuscation of your existing integer keys, with no schema changes. Choose UUIDs or ULIDs when identifiers must be non-enumerable, generated client-side, or safe to expose without any shared secret. Hashids also does not replace authorization, so a UUID model still needs policy checks. Many teams start with hashids on a few non-critical models and migrate to UUIDs where the security requirement is higher.