Download the PHP package channor/hashed-route-key without Composer

Opaque Route Key

Deterministic, model-level opaque route keys for Laravel.

Replaces sequential integer IDs in URLs with compact, HMAC-verified route keys without storing anything extra in the database:

The result is deterministic and decodable. It is obfuscation with integrity checks, not encryption, not secrecy, and not authorization.

Note: This package is not a security boundary and does not replace authentication, authorization, or signed URLs.

The Eloquent trait keeps route-key generation and route binding on the model itself, while deriving distinct salts per model so the same integer ID produces different route keys across models by default.

Installation

Supported targets:

• PHP 8.2, 8.3, and 8.4
• Laravel 11 and 12

Laravel package discovery registers the service provider automatically. If your application disables package discovery, register it manually in bootstrap/providers.php:

Publish config when you need to customize behavior:

Quick Start

Add the trait to an Eloquent model with an integer primary key:

That is enough for route model binding and route() URL generation to use the opaque key. Serialization includes the computed route_key by default.

Upgrade To V2

Version 2.0.0 removes the deprecated hashed-route-key compatibility layer kept during v1.x. See the v2 upgrade guide for package, import, and config migration steps.

Configuration

Once URLs are public, keep the effective salt and per-model strategy settings stable. Changing salt, salt suffix, payload length, check length, offset multiplier, reserved words, or reserved-word attempt settings can invalidate existing URLs or change future generated URLs for affected IDs.

Reserved Words

reserved_words prevents the codec from emitting route keys that collide with route paths such as create, edit, or new. The default list is empty because reserved route words are application-specific. With the default encoding settings, generated keys are at least 7 characters long, so shorter words cannot be emitted.

Manual reserved words are case-sensitive by default. Reserving account will not reserve aCcOuNt unless reserved_words_case_sensitive is false.

When auto_reserve_model_names is true, each model using the trait reserves its lowercase singular and plural class basename, for example account and accounts for Account. These model-name reservations are always matched case-insensitively.

If a generated key is reserved, the codec retries deterministic alternate encodings up to reserved_word_max_attempts. If every attempt collides, encoding throws a RuntimeException. Existing keys remain decodable even if you later reserve a word that was previously emitted.

Customization

Override strategy methods on a model when the defaults do not fit:

By default, the codec salt is:

routeKeySaltSuffix() defaults to snake_case(class_basename(Model::class)). Keep custom suffixes stable once URLs are public.

To customize the serialized attribute:

Contract Tests

Generate app-level stability tests before changing route-key settings:

Useful options:

• --force overwrites existing generated tests
• --path=tests/Feature/RouteKeys changes the output directory
• --namespace=App\\Domain\\People\\Models changes the --all discovery namespace
• --model-path=src/Domain/People/Models sets discovery for non-App\\... namespaces

Generated model tests pin strategy values and fixed route-key outputs. The reserved config test pins reserved-word settings.

Decode Failures

When an opaque key is invalid, tampered, wrong-model, or malformed:

• OpaqueRouteKeyCodec::decode() returns null
• route model binding queries WHERE id = -1, which matches nothing and results in a 404
• $model->route_key returns null on unsaved models

Advanced Usage

If you need the lower-level codec directly, use the same model-specific salt strategy as the trait:

Capacity with the default base-62 alphabet:

The payload starts at min_payload_length characters and adds characters as IDs grow beyond what the current length can represent. offset_multiplier shifts where these length boundaries fall.

Alternatives

vinkla/laravel-hashids and cybercog/laravel-optimus are relevant alternatives for Laravel applications that want obfuscated identifiers. Either may be a better fit depending on your needs and existing conventions.

Notes

• Only non-negative integer IDs are supported.

Development Note

This package was developed with LLM assistance. Final design, review, and release decisions remain with the maintainer.