dyrynda / laravel-efficient-uuid
A package to extend Laravel migrations adding a more efficient storage of UUID fields in your database
Installs: 1 004 196
Dependents: 7
Suggesters: 2
Security: 0
Stars: 305
Watchers: 8
Forks: 39
Open Issues: 6
Type:utility
Requires
- php: ^8.1
- dyrynda/laravel-model-uuid: ^7.0
- illuminate/container: ^10.0
- illuminate/contracts: ^10.0
- illuminate/database: ^10.0
- ramsey/uuid: ^4.7
Requires (Dev)
- laravel/legacy-factories: ^1.3
- mockery/mockery: ^1.4.4
- orchestra/testbench: ^8.0
- phpunit/phpunit: ^9.6.0 || ^10.0.7
README
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