PHPackages                             alesitom/hybrid-id-laravel - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. alesitom/hybrid-id-laravel

ActiveLibrary[Database & ORM](/categories/database)

alesitom/hybrid-id-laravel
==========================

Laravel integration for HybridId — Eloquent trait, service provider, and config

v2.1.0(2mo ago)00[2 PRs](https://github.com/alesitom/hybrid-id-laravel/pulls)MITPHPPHP ^8.3CI passing

Since Feb 16Pushed 2mo agoCompare

[ Source](https://github.com/alesitom/hybrid-id-laravel)[ Packagist](https://packagist.org/packages/alesitom/hybrid-id-laravel)[ RSS](/packages/alesitom-hybrid-id-laravel/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (4)Dependencies (7)Versions (12)Used By (0)

HybridId for Laravel
====================

[](#hybridid-for-laravel)

Laravel integration for [HybridId](https://github.com/alesitom/hybridId_package) — compact, time-sortable unique IDs as a drop-in UUID replacement for Eloquent models.

[![Tests](https://camo.githubusercontent.com/dec207a08cccd825604c953ff0725e94d902037c0ecba91bb9bb869449fa11c4/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f616c657369746f6d2f6879627269642d69642d6c61726176656c2f63692e796d6c3f7374796c653d666c61742d737175617265266c6162656c3d7465737473)](https://github.com/alesitom/hybrid-id-laravel/actions)[![Coverage](https://camo.githubusercontent.com/b0cbcab9a6fa1690abc6c519d7f3bd34f45cd0187d45db6654bc06d5e39549ef/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636f762f632f6769746875622f616c657369746f6d2f6879627269642d69642d6c61726176656c3f7374796c653d666c61742d737175617265)](https://codecov.io/gh/alesitom/hybrid-id-laravel)[![PHPStan](https://camo.githubusercontent.com/38722f611b1083b1ea52358c73c42c40d08de176989d463cd9d588d25b97da48/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d6c6576656c2532306d61782d626c75653f7374796c653d666c61742d737175617265)](https://phpstan.org/)

Installation
------------

[](#installation)

```
composer require alesitom/hybrid-id-laravel
```

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

Quick Start
-----------

[](#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
---------

[](#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](https://github.com/alesitom/hybridId_package#collation-important-for-mysqlmariadb) for details.

Configuration
-------------

[](#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
----------

[](#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](https://github.com/alesitom/hybridId_package/blob/main/docs/blind-mode.md) for details.

Dependency Injection
--------------------

[](#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
--------

[](#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
------------

[](#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
------------

[](#requirements)

- PHP 8.3, 8.4, or 8.5
- Laravel 11 or 12
- [alesitom/hybrid-id](https://github.com/alesitom/hybridId_package) ^4.1 (installed automatically)

License
-------

[](#license)

MIT

###  Health Score

38

—

LowBetter than 85% of packages

Maintenance82

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 91.7% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

4

Last Release

89d ago

Major Versions

v1.0.1 → v2.0.02026-02-17

### Community

Maintainers

![](https://www.gravatar.com/avatar/027a2a89c88ec6e75a1acd67c7149eb5828555771423544a686adca49bf817d1?d=identicon)[CheerfulBox8976](/maintainers/CheerfulBox8976)

---

Top Contributors

[![alesitom](https://avatars.githubusercontent.com/u/22220729?v=4)](https://github.com/alesitom "alesitom (11 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)")

---

Tags

laraveleloquentunique-iduuid-alternativetime-sortablehybrid-id

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/alesitom-hybrid-id-laravel/health.svg)

```
[![Health](https://phpackages.com/badges/alesitom-hybrid-id-laravel/health.svg)](https://phpackages.com/packages/alesitom-hybrid-id-laravel)
```

###  Alternatives

[cviebrock/eloquent-sluggable

Easy creation of slugs for your Eloquent models in Laravel

4.0k13.6M253](/packages/cviebrock-eloquent-sluggable)[tucker-eric/eloquentfilter

An Eloquent way to filter Eloquent Models

1.8k4.8M26](/packages/tucker-eric-eloquentfilter)[watson/validating

Eloquent model validating trait.

9723.3M47](/packages/watson-validating)[cybercog/laravel-love

Make Laravel Eloquent models reactable with any type of emotions in a minutes!

1.2k302.7k1](/packages/cybercog-laravel-love)[cviebrock/eloquent-taggable

Easy ability to tag your Eloquent models in Laravel.

567694.8k3](/packages/cviebrock-eloquent-taggable)[reedware/laravel-relation-joins

Adds the ability to join on a relationship by name.

2121.2M13](/packages/reedware-laravel-relation-joins)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)