README

Laravel integration for HybridId — compact, time-sortable unique IDs as a drop-in UUID replacement for Eloquent models.

Installation

composer require alesitom/hybrid-id-laravel

The service provider is auto-discovered. No manual registration needed.

Quick Start

Add the HasHybridId trait to any model:

use HybridId\Laravel\HasHybridId;

class User extends Model
{
    use HasHybridId;

    protected static string $idPrefix = 'usr';
}

That's it. New models automatically get a HybridId on creation:

$user = User::create(['name' => 'Jane']);
$user->id;  // usr_0VBFDQz4CYRtntu09sbf

Migration

Your primary key column must be a string, not an auto-incrementing integer:

Schema::create('users', function (Blueprint $table) {
    $table->string('id', 29)->collation('ascii_bin')->primary();
    // ... other columns
    $table->timestamps();
});

Use ascii_bin collation on MySQL/MariaDB to preserve case-sensitive ordering. See core docs for details.

Configuration

Publish the config file:

php artisan vendor:publish --tag=hybrid-id-config

This creates config/hybrid-id.php:

return [
    'profile' => env('HYBRID_ID_PROFILE', 'standard'),
    'node' => env('HYBRID_ID_NODE'),
    'require_explicit_node' => (bool) env('HYBRID_ID_REQUIRE_NODE', false),
    'blind' => (bool) env('HYBRID_ID_BLIND', false),
    'blind_secret' => env('HYBRID_ID_BLIND_SECRET'),
];

Set HYBRID_ID_REQUIRE_NODE=1 in production to enforce explicit node assignment.

Blind Mode

Enable blind mode to HMAC-hash timestamps and node info, making creation time unextractable:

HYBRID_ID_BLIND=true
HYBRID_ID_BLIND_SECRET=base64encodedvalue...

Generate a secret: php -r "echo base64_encode(random_bytes(32)) . PHP_EOL;"

See Blind Mode docs for details.

Dependency Injection

The service provider binds IdGenerator as a singleton. Inject it anywhere:

use HybridId\IdGenerator;

class OrderService
{
    public function __construct(
        private readonly IdGenerator $idGenerator,
    ) {}

    public function createOrder(): Order
    {
        return Order::create([
            'id' => $this->idGenerator->generate('ord'),
            'status' => 'pending',
        ]);
    }
}

Prefixes

Set $idPrefix on your model for Stripe-style self-documenting IDs:

class Order extends Model
{
    use HasHybridId;
    protected static string $idPrefix = 'ord';
}

class Invoice extends Model
{
    use HasHybridId;
    protected static string $idPrefix = 'inv';
}

Omit $idPrefix for unprefixed IDs.

How It Works

• HasHybridId hooks into Eloquent's creating event
• Sets $keyType = 'string' and $incrementing = false automatically
• If the model's primary key is empty at creation time, generates a HybridId
• If the primary key is already set (e.g., manual assignment), it is not overwritten
• The generator instance is resolved from the container (singleton)

Requirements

• PHP 8.3, 8.4, or 8.5
• Laravel 11 or 12
• alesitom/hybrid-id ^4.1 (installed automatically)

License

MIT