Download the PHP package atldays/laravel-hashids without Composer

Laravel Hashids

atldays/laravel-hashids helps Laravel apps use hash IDs as one clean, consistent flow.

Instead of handling encoding, decoding, validation, routing and API output in different places, the package keeps everything working together:

• generating hash IDs on models
• resolving models from hash IDs
• route model binding
• validation rules
• request decoding in FormRequest
• serialized API output
• model-aware artisan commands

Under the hood, it is powered by hashids/hashids, while adding a Laravel-first developer experience around models, requests, validation and routing.

Your application can keep working with plain numeric values internally, while the outside world works with hash IDs in a predictable way.

Features

• Model trait for generating and resolving hash IDs
• Query helpers like findByHashId() and whereHashId()
• Optional route model binding with hash IDs
• Validation rules for single and multiple values
• FormRequest integration for automatic decoding
• Wildcard request field support like items.*.author
• Optional serialized output that replaces the source column with a hash ID
• Model attributes for configuring hash ID source column and salt
• Legacy registry support for custom and old salts
• Artisan commands for model-specific encode and decode

Installation

Install the package via Composer:

Publish the config file if you want to customize the defaults:

If you plan to contribute, please also read CONTRIBUTING.md.

Quick Start

Add HasHashId to your model:

Now you can:

Optional Model Contract

The HasHashId trait is enough for normal package usage. You do not need an interface just to generate hash IDs, resolve route bindings, validate request fields, or use the request helpers.

If you want a full typed contract for your own services, package integrations or PHPStan-friendly dynamic model classes, also implement HasHashIdModel:

This is useful when your own code accepts hash ID capable models through type hints:

Core Concept

The package is built around two layers:

1. Internal application values Your models and database keep using numeric values.

2. External application values Routes, requests, validation and serialized output can use hash IDs instead.

The hashid.enabled config option controls that external behavior.

When it is enabled:

• routes use hash IDs
• validation expects hash IDs
• FormRequest decoding expects hash IDs
• serialized output can expose hash IDs

When it is disabled:

• the core HashId service still works
• model methods still work
• external integrations use plain numeric values instead

That makes local debugging and gradual adoption much easier.

For a full request-response cycle, use getHashIdInput() when sending model identifiers to the client and findByHashIdInput() when accepting them back:

When hashid.enabled is true, getHashIdInput() returns a hash ID string. When it is false, it returns the plain numeric source value.

Basic Model Usage

Generate Hash IDs

getHashId() always returns the hashed representation when the model has a source value. getHashIdInput() follows hashid.enabled and is the safer choice for identifiers you send to a client and expect back in a request.

Find Models By Hash ID

Find Models By External Input

Use these helpers when the value comes from a request, route or another external input and should follow the hashid.enabled config:

When hashid.enabled is true, the input is decoded as a hash ID. When it is false, the input is resolved as a plain numeric value.

For symmetry, send values out with getHashIdInput():

Query Builder Helpers

Route Model Binding

If you want route model binding to work with hash IDs, add HasHashIdRouting:

Then standard Laravel route model binding works:

And route generation also uses the hash ID:

Validation

The package provides two rules:

• HashId — validates that the value is a valid hash ID
• HashIdExists — validates that the hash ID is valid and the model exists

Single Value

Arrays

The rules are nullable-friendly by design, so they work naturally with Laravel rules like required and nullable.

Validation messages are translated through the package translation files, and you can override them in your application the same way you override other Laravel package translations.

First publish the package translations:

Example:

Form Requests

For API-heavy projects, FormRequest integration is one of the most useful parts of the package.

It lets you accept hash IDs from the outside world, validate them, and then work with plain numeric values or resolved models inside your request and controllers.

Use the InteractsWithHashIds trait:

After validation:

• author becomes an integer model value
• posts becomes an array of integer model values

Resolve Models From Request Fields

Dot Notation And Wildcards

The request layer supports nested fields:

And then:

Serialized Output

If you want your model to expose hash IDs in serialized output, add SerializesHashId:

When hashid.enabled is true, the source column used by the model is replaced in serialized output:

Instead of:

you get:

When hashid.enabled is false, serialization stays plain and returns numeric values.

Model Attributes

The package supports PHP attributes for model configuration.

Custom Source Column

Custom Salt

Salt From Class Name

Salt From Table Name

Trait-Level Defaults

Attributes can also live on traits, which is useful when you want shared behavior across multiple models.

Model-level attributes still take priority over trait-level attributes.

Legacy And Custom Salt Mapping

If you need to support old salts, old namespaces or legacy model mappings, use HashIdRegistry.

Example:

This is especially useful when you moved models between namespaces or repositories but still need old hash IDs to keep working.

Artisan Commands

The package provides model-aware commands:

These commands use the model's own hash ID configuration, including its salt logic.

Configuration

enabled

Controls the package's external behavior.

When enabled, the package uses hash IDs in:

• route model binding
• validation
• request decoding
• serialized output

When disabled, those integrations use plain numeric values instead.

salt

Default salt for the core HashId service.

length

The generated hash ID length.

alphabet

The alphabet passed to the underlying hashids/hashids encoder.

Core HashId Service

If you need the low-level service directly, you can use the HashId facade:

If you need a custom runtime configuration, you can create a configured HashId instance directly:

You can also override only the values you need:

Local Development

Install dependencies in the same Docker-based environment used by the project:

Run formatting and tests: