noolan/my-uuid

Easily use UUIDs as primary keys

dev-master 2020-02-26 19:55 UTC

MIT

• Nolan Neustaeter

README

Simplifies using UUIDs in MySQL and Laravel

https://noolan.github.io/my-uuid/

Install

composer require noolan/my-uuid

Configure

Copy Config File

php artisan vendor:publish --provider Noolan\\MyUuid\\Service

The settings for this package can now be edited in config/myuuid.php.

Available Settings

Key	Type	Default	Description
mysql_8	Boolean	true	MySQL 8 adds two new functions, UUID_TO_BIN and BIN_TO_UUID that simplify working with UUIDs. If mysql_8 is true, those new functions will be used instead of the mashup of HEX, UNHEX, and REPLACE that is otherwise required. If you are unsure which version of MySQL you have you can run the php artisan myuuid:version command detailed below.
connection	String	'' (empty string)	The name of the database connection to use as defined in your config/database.php file. An empty string will result in your default connection being used.

Checking Configuration

There are two Artisan commands included with this package that help with configuration; version and check.

Command	Arguments	Description	Example
myuuid:version	(none)	Outputs the MySQL version of the configured connection.	php artisan myuuid:version
myuuid:check	(none)	Checks the current configuration against the database to see if there are issues.	php artisan myuuid:check

Usage

Instantiation

All the functionality is accessed through the MyUuid facade.

use MyUuid;
/* ... */
public function doAThing()
{
    $myUuid = MyUuid::alter('examples');
    /* ... */
}

Chaining

Most methods on the MyUuid class return the object so methods can be chained.

$myUuid->addColumn('uuid', 'blob', 16)
$myUuid->addColumn('parent_id', 'varbinary', 36)
$myUuid->addIndex();

$myUuid->run();

// Can be re-written as:

$myUuid->addColumn('uuid', 'blob', 16)
       ->addColumn('parent_id', 'varbinary', 36)->addIndex()
       ->run();

Note: If a non-column function is called without a column name parameter, MyUuid uses the last added column as a default.

Convenience Functions

There are several functions that make it easy to perform common tasks as long as you don't need to deviate from the default parameters.

/* Add an auto-populating, 16 byte, binary column named 'id'
   and use it as the table's primary key */

$myUuid->addPrimaryUuid('id');

// is equivalent to:

$myUuid->addColumn('id', 'binary', 16)
       ->addIndex('primary')
       ->addTrigger();

Executing Queries and Rolling Back Migrations

Columns and indexes created with MyUuid can be dropped with Laravel's Schema builder. The only thing you have to manually drop is triggers.

// removes auto-population trigger attached to the 'id' column
$myUuid->dropTrigger('id')->run();

API

Uuid Methods

alter

(String $table)
returns: new UuidSchema

getVersion

()
returns: String MySql version

getTrustFunctionCreatorsSetting

()
returns: Boolean on

UuidSchema Methods

addColumn

(String $name, [String $type, Integer $length, String $virtualTarget])
returns: UuidSchema self

addIndex

([String $type, String $column, String $cname, Integer $length])
returns: UuidSchema self

addTrigger

([String $column])
returns: UuidSchema self

dropTrigger

(String $column) returns: UuidSchema self

run

() returns: null

UuidSchema Convenience Methods

addPrimaryUuid

(String $name)
returns: UuidSchema self

addAutoUuid

(String $name)
returns: UuidSchema self

addFriendlyUuid

(String $name, String $target)
returns: UuidSchema self

withFriendly

(String $target)
returns: UuidSchema self

addIndexedUuid

(String $name)
returns: UuidSchema self

index

([String $type])
returns: UuidSchema self

addForeignUuid

(String $name)
returns: UuidSchema self

Example

<?php

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

use MyUuid;

class CreateExamplesTable extends Migration
{
  /**
  * Run the migrations.
  *
  * @return void
  */
  public function up()
  {
    Schema::create('examples', function (Blueprint $table) {
      $table->timestamps();
      $table->softDeletes();

      $table->string('title')->index();
      $table->text('description');
      $table->longText('code');
    });

    MyUuid::alter('examples')
      ->addPrimaryUuid('id')->withFriendly('uuid')
      ->addForeignUuid('category_id')
      ->run();
  }

  /**
  * Reverse the migrations.
  *
  * @return void
  */
  public function down()
  {
    MyUuid::alter('examples')->dropTrigger('id')->run();
    Schema::dropIfExists('characters');
  }
}