verbanent/eloquent-binary-uuid

Ordered binary UUID in Laravel / Eloquent based on UUID version 1

v1.10.0 2026-01-13 18:26 UTC

Requires

• php: ^7.3|^8
• ramsey/uuid: ^3.8|^4

Requires (Dev)

• laravel/framework: ^6.20.26|^7|^8|^9|^10.48.29|^11|^12
• mockery/mockery: ^1
• phpunit/phpunit: ^9

MIT

• Radek Ziemniewicz

• uuid
• laravel
• binary
• eloquent
• hex
• ordered

README

Based on articles about the optimization of UUID storage in databases, I decided to write a simple library that allows this in my projects. I based on the information available here:
https://www.percona.com/blog/2014/12/19/store-uuid-optimized-way/
https://percona.community/blog/2018/10/12/generating-identifiers-auto_increment-sequence/

The package currently only supports MySQL.

Installation

Please install the package via Composer:

composer require verbanent/eloquent-binary-uuid

Basic example

This example keeps things simple: Foo and Bar both use UUID primary keys, and Bar.foo_id references Foo.id.

Migrations

use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

Schema::create('foos', function (Blueprint $table) {
    $table->uuid('id')->primary();
    $table->string('name')->nullable();
    $table->timestamps();
});

Schema::create('bars', function (Blueprint $table) {
    $table->uuid('id')->primary();
    $table->uuid('foo_id');
    $table->string('title')->nullable();
    $table->timestamps();

    $table->foreign('foo_id')->references('id')->on('foos')->cascadeOnDelete();
});

Models

namespace App\Models;

use Verbanent\Uuid\AbstractModel;

class Foo extends AbstractModel
{
    protected $fillable = ['name'];

    public function bars()
    {
        return $this->hasMany(Bar::class, 'foo_id');
    }
}

namespace App\Models;

use Verbanent\Uuid\AbstractModel;
use Verbanent\Uuid\Traits\ForeignBinaryUuidSupportableTrait;

class Bar extends AbstractModel
{
    protected $fillable = ['title'];

    public function foo()
    {
        return $this->belongsTo(Foo::class, 'foo_id');
    }
}

Usage

$foo = \App\Models\Foo::create(['name' => 'Alpha']);

$bar = new \App\Models\Bar(['title' => 'Child']);
$bar->foo()->associate($foo);
$bar->save();

Examples

More scenarios are documented in the examples/ directory:

• examples/01-single-model-uuid-primary-key.md
• examples/02-two-models-uuid-pk-and-fk.md
• examples/03-creating-entities-with-binary-uuid.md
• examples/04-creating-entities-with-string-uuid.md
• examples/05-querying.md

Configuration

If you want a global default UUID column name, publish the config and set the environment variable.

1. Publish the config file:

php artisan vendor:publish --provider="Verbanent\\Uuid\\Providers\\BinaryUuidServiceProvider" --tag=binary-uuid-config

1. Set the default column name in .env:

BINARY_UUID_DEFAULT_COLUMN=uuid

1. Refresh config:

php artisan config:clear
# or
php artisan config:cache

Per-model override still works and takes precedence:

protected $uuidColumn = 'custom_uuid';

Unit tests

Run this command if you want to check unit tests:

./vendor/bin/phpunit

Or if you want to check code coverage:

phpdbg -qrr vendor/bin/phpunit --coverage-html coverage tests