Ordered binary UUID in Laravel / Eloquent

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

2. Set the default column name in .env:

BINARY_UUID_DEFAULT_COLUMN=uuid

3. Refresh config:

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

Per-model override still works and takes precedence:

protected $uuidColumn = 'custom_uuid';

Troubleshooting

When the package reads a column that does not hold a binary UUID, it says so directly instead of letting ramsey/uuid fail on the raw value:

Column "id" on App\Models\Category does not contain a 16-byte binary UUID
(found a 4-byte string). Point $uuidColumn on the model, or
binary-uuid.default_column, at the column holding the binary UUID.

UUIDs are stored as 16 raw bytes, so the column the package reads has to be the binary one — set it per model with protected $uuidColumn = 'uuid'; or globally with BINARY_UUID_DEFAULT_COLUMN. Assigning a value that is neither a UUID in string form nor 16 raw bytes throws InvalidBinaryUuidException while the model is being created, instead of writing it to the database.

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