Laravel Human Id Laravel Package

Getting Started

lemaur/laravel-human-id generates memorable, human-readable primary keys (e.g. brave-otter-42) instead of auto-increment integers — useful for public-facing URLs, support references, and anywhere an opaque numeric ID leaks volume or looks unfriendly.

Minimal setup:

composer require lemaur/laravel-human-id
php artisan vendor:publish --tag="human-id-config"

Then make the model's key a string and opt in via the trait:

// migration
$table->string('id')->primary();

// app/Models/Post.php
use LeMaur\HumanId\Traits\HasHumanId;

class Post extends Model
{
    use HasHumanId;
}

Where to look first:

1. The published config/human-id.php — separator, word/segment count, and the adjective/noun word lists you'll want to customise per domain.
2. The HasHumanId trait — it wires generation into the creating event and flips $incrementing/$keyType for you.
3. The HumanId facade — for generating IDs outside of Eloquent (imports, external references, batch jobs).

First use case: replace Route::get('/posts/{post}') integer binding with the model's own human key. No extra route-key configuration is needed because the human ID is the primary key.

Implementation Patterns

Model trait (the default path). Add HasHumanId to any model whose key should be human-readable. On creating, the trait fills the id attribute before insert, so Post::create([...]) just works and the model is immediately routable:

$post = Post::create(['title' => 'Hello']);
$post->id; // "calm-fox-42"
route('posts.show', $post); // /posts/calm-fox-42

Explicit generation via the facade. For non-Eloquent contexts — invoice numbers, job correlation IDs, seeded fixtures — call the generator directly and pass uniqueness context if you need collision checking against a table:

use LeMaur\HumanId\Facades\HumanId;

$reference = HumanId::generate();

Per-model configuration. Rather than one global word list, define domain-specific vocabularies in config (e.g. animals for users, colours for tags) and select the relevant set per model. This keeps IDs on-brand and makes them guessable-by-category, which is often desirable for support workflows.

Route keys and lookups. Because the key is the primary key, find(), findOrFail(), route model binding, and whereKey() all behave normally. Keep controllers on findOrFail($humanId) rather than string-matching slugs — you get 404 semantics for free.

Integration points to wire up deliberately:

• API resources: expose id as-is; it is already URL-safe.
• Foreign keys: any referencing column must be string of matching length, not unsignedBigInteger.
• Factories/seeders: let the trait generate, or set id explicitly for deterministic test fixtures.
• Soft deletes: fine — the key remains stable across restore.

Gotchas and Tips

• Schema first. A string PK means $incrementing = false and $keyType = 'string'. If the trait is added but the migration still declares $table->id(), inserts fail. Change both together, and update every foreign key that points at the table.
• Keep id out of $fillable. Mass-assignment of id will bypass generation (or produce inconsistent behaviour). Generate, don't accept, the key from request input.
• Uniqueness is a DB round-trip. Generation typically checks the table for collisions and retries; on high-volume inserts this adds a query per create. Watch for retry storms if your word list is small — tune segment count/word pool before scaling writes.
• Collation can bite. MySQL's default case-insensitive collation means Calm-Fox and calm-fox collide at the DB level even if the generator treats them as distinct. Normalise casing in config or use a binary/case-sensitive collation.
• Config caching. After editing config/human-id.php, run php artisan config:clear locally and remember config:cache in deploy scripts — stale cached word lists are a classic "why is it still generating old words" moment.
• Queue and retry safety. Generated IDs are computed at creating, so retried jobs produce a fresh value per attempt; if downstream systems depend on the ID, persist the model before dispatching or use ShouldBeUnique semantics carefully.
• Extension point. The cleanest customisation is subclassing/overriding the trait's generation method on the model itself rather than forking the package — keeps your rules (prefixes, tenant scoping, reserved words) local and testable.
• Version note (1.1.0). This release is a minor bump from 1.0.0 with no breaking changes signalled; treat it as a safe upgrade, but re-run your config publish diff to see whether the shipped human-id.php gained new keys, and re-run the suite after composer update since trait internals around the creating hook are the most likely place for subtle behaviour shifts.