README

Important

If you need support for Laravel 11.x and above, the functionality of this package has been combined with laravel-model-uuid.

Introduction

This package extends the default grammar file for the given MySQL connection adding an efficientUuid blueprint method that creates a binary(16) field.

As of 3.0, this package no longer overrides Laravel's default uuid method, but rather adds a separate efficientUuid field, due to compatibility issues with Laravel Telescope (#11).

As of 4.0, this package uses a custom cast to provide casting functionality into your models.

Note: This package purposely does not use package discovery, as it makes changes to the MySQL schema file, which is something you should explicitly enable.

MySQL, SQLite, and PostgreSQL are the only supported connection types, although I welcome any pull requests to implement this functionality for other database drivers.

Note that doctrine/dbal does not appear to support changing existing uuid fields, and doing so would cause your existing values to be truncated in any event.

For more information, check out this post on storing and working with UUID in an optimised manner.

Using UUIDs in Laravel is made super simple in combination with laravel-model-uuid. Note that when using laravel-model-uuid, if you are not casting your UUIDs or calling the query builder directly, you'll need to use the getBytes method when setting the UUID on the database, otherwise your values will be truncated. Depending on your MySQL/MariaDB configuration, this may lead to application errors due to strict settings. See (#1) for more information.

This package is installed via Composer. To install, run the following command.

composer require dyrynda/laravel-efficient-uuid

Register the service provider in your config/app.php configuration file:

'providers' => [
    ...
    Dyrynda\Database\LaravelEfficientUuidServiceProvider::class,
],

Migrations

There is nothing special needed for this to function, simply declare a uuid column type in your migration files. If you plan on querying against the UUID column, it is recommended that you index the column, but avoid making it the primary key.

Schema::create('posts', function (Blueprint $table) {
    $table->increments('id');
    $table->efficientUuid('uuid')->unique();
    $table->string('title');
    $table->text('body');
    $table->timestamps();
});

Casting

You will need to add a cast to your model when using laravel-model-uuid in order to correctly set and retrieve UUID from your MySQL database with binary fields.

<?php

namespace App;

use Dyrynda\Database\Casts\EfficientUuid;
use Dyrynda\Database\Support\GeneratesUuid;
use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    use GeneratesUuid;

    protected $casts = [
        'uuid' => EfficientUuid::class,
    ];
}

Querying by UUID

If you want to find a record by a string UUID, you need to use scope:

Post::whereUuid('25b112a9-499a-4627-9ea0-72cd8694aee3')->first();

Validation

Should you wish to use the efficient UUID column as part of your validation strategy, you may use the EfficientUuidExists rule as normal.

use Dyrynda\Database\Rules\EfficientUuidExists;

public function update(Request $request, User $user)
{
    $request->validate([
        // Using the default column name
        'uuid' => [new EfficientUuidExists(Post::class)],

        // Using a custom column name
        'custom_uuid' => [new EfficientUuidExists(Post::class, 'custom_uuid')],
    ]);
}

Support

If you are having general issues with this package, feel free to contact me on Twitter.

If you believe you have found an issue, please report it using the GitHub issue tracker, or better yet, fork the repository and submit a pull request.

If you're using this package, I'd love to hear your thoughts. Thanks!

Treeware

You're free to use this package, but if it makes it to your production environment you are required to buy the world a tree.

It’s now common knowledge that one of the best tools to tackle the climate crisis and keep our temperatures from rising above 1.5C is to plant trees. If you support this package and contribute to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.

You can buy trees here

Read more about Treeware at treeware.earth