README

Generate Nanoid-based, Stripe-style IDs for your Eloquent models.

Installation

composer require malico/laravel-nanoid

Quick Start

Add HasNanoids to your model:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Malico\LaravelNanoid\HasNanoids;

class Book extends Model
{
    use HasFactory;
    use HasNanoids;
}

Use a string primary key in your migration:

public function up(): void
{
    Schema::create('books', function (Blueprint $table) {
        $table->string('id')->primary();
        $table->timestamps();
    });
}

You can also scaffold migrations with:

php artisan make:nanoid-migration

make:nanoid-migration accepts the same arguments as make:migration.

Configuration

You can configure generated IDs per model with these properties (or methods with the same names):

nanoidPrefix: static prefix, for example ord_
nanoidLength: fixed length (10) or random range ([10, 20])
nanoidAlphabet: allowed characters
nanoidFormat: structured format like {3}-{4}

Each option supports either:

A single value for all unique ID columns
A keyed array per column

`nanoidPrefix`

// One prefix for all generated ids
protected $nanoidPrefix = 'p-';

// Per-column prefixes
protected $nanoidPrefix = ['id' => 'p-', 'username' => 'u_'];

`nanoidLength`

// One fixed length for all generated ids
protected $nanoidLength = 12;

// Random length between min and max for all generated ids
protected $nanoidLength = [2, 5];

// Per-column fixed length
protected $nanoidLength = ['id' => 7, 'username' => 12];

// Per-column ranged length (min, max)
protected $nanoidLength = ['id' => [2, 5], 'username' => [8, 10]];

// Invalid: range must have exactly two values [min, max]
protected $nanoidLength = ['id' => [2]];

`nanoidAlphabet`

// One alphabet for all generated ids
protected $nanoidAlphabet = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789';

// Per-column alphabets
protected $nanoidAlphabet = [
    'id' => 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789',
    'username' => 'abcdefghijklmnopqrstuvwxyz',
];

`nanoidFormat`

// One format for all unique id columns
protected $nanoidFormat = 'u_{4}-{4}';

// Per-column formats
protected $nanoidFormat = ['id' => 'p-{7}', 'username' => 'u_{4}-{4}'];

Full model example

<?php

use Illuminate\Database\Eloquent\Model;
use Malico\LaravelNanoid\HasNanoids;

class SessionToken extends Model
{
    use HasNanoids;

    protected $nanoidAlphabet = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789';
    protected $nanoidPrefix = [
        'id' => 'p-',
    ];
    protected $nanoidLength = 12;
    protected $nanoidFormat = [
        'username' => 'u_{8}',
    ];

    public function uniqueIds(): array
    {
        return ['id', 'username'];
    }
}

// id: p-8F4Z2K9T7Q1M
// username: u_A8K9P2QW

Format Patterns

Use nanoidFormat when you want readable, segmented IDs.

Supported placeholders:

{n} generates exactly n random characters
{min-max} generates a random length between min and max

All other characters are kept as-is (-, _, ., spaces, and so on).

class TrackingCode extends Model
{
    use HasNanoids;

    protected $nanoidFormat = 'TRK-{3}-{3-4}-{6}';
}

// TRK-X9a-k2Pm-8Qw1Zr
// TRK-L0p-r7A-2bV9tK

class Coupon extends Model
{
    use HasNanoids;

    protected $nanoidAlphabet = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789';
    protected $nanoidFormat = '{4} {4}';
}

// 7KQ2 M9TZ

Rules:

If nanoidFormat is set, it fully controls the generated shape
nanoidFormat cannot be combined with nanoidPrefix
nanoidFormat cannot be combined with nanoidLength
Without nanoidFormat, generation falls back to nanoidPrefix + nanoidLength
With per-column arrays, these conflict rules apply per column

Benchmark

Run the included micro-benchmark:

php benchmarks/nanoid.php

Choosing an ID Type

Use this package when you want random, non-sequential, human-friendly IDs (for example p-8F4Z2K9T7Q1M)
Use Laravel HasUlids when you want sortable IDs that preserve creation order better
Use auto-incrementing integers when you need simple sequential IDs and the best insert locality

If your system requires strictly incremental IDs, this package is not the right tool.

Safety Notes

Short IDs are easier to collide and easier to guess; increase length for public or sensitive resources
NanoID's own guidance compares default NanoID entropy with UUID v4 (similar collision profile)
Always choose size/alphabet based on your scale and threat model
For custom sizes, check collision estimates with: https://zelark.github.io/nano-id-cc/

If you are upgrading from 0.x, see UPGRADE.MD.

Author

Ndifon Desmond Yong

malico / laravel-nanoid

Maintainers

Details