README

Eloquent UUID

Simple and flexible Laravel package that adds support for UUID generation automatically for any Eloquent model.

Generate uuid automatically.
Choose a custom name for the uuid column in your table. (default 'uuid')
Choose the version of the generated uuid. (default '4')
Checks for uuid version and column name. (throws the InvalidUuidVersionException and MissingUuidColumnException exceptions)
Prevents update on uuid value.

What is a UUID?

A universally unique identifier (UUID) is a 128-bit number used to identify information in computer systems. is a 36 character long identifier made up of 32 alphanumeric characters with four hyphens in amongst it. For example:123E4567-E89b-12D3-A456-426655440000 containing letters and numbers. that will uniquely identify something. you can read more here.

Installation

You can install the package via Composer:

composer require your-app-rocks/eloquent-uuid

or via composer.json file

{
    "require": {
        "your-app-rocks/eloquent-uuid": "~2"
    }
}

Usage

Create table

Create your table with a uuid column. For example:

<?php

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

Create model

In your eloquent model, add trait HasUuid:

<?php

namespace App\YourNameSpace;

use Illuminate\Database\Eloquent\Model;
use YourAppRocks\EloquentUuid\Traits\HasUuid;

class User extends Model
{
    use HasUuid;
}

Create Controller

<?php

namespace App\YourNameSpace;

use App\YourNameSpace\User;
use Illuminate\Http\Request;

class UserController extends Controller
{

    /**
     * When a new record is inserted into the table `(with the create() or save() methods)`,
     * Trait "HasUuid" will automatically generate a uuid version 4* for the 'uuid' column of your schema.
     */
    public function store(Request $request)
    {
        $user = User::create($request->all()); // Automatically generate a uuid

        return $user->getUuid() // Return UUID value.
    }

    /**
     * Get User by custom 'UUID' key name - Implicit Binding.
     * See https://laravel.com/docs/5.8/routing#route-model-binding
     *
     * @param User $user
     * @return void
     */
    public function show(User $user)
    {
        return $user;
    }

    //OR

    /**
     * Get User by scope query.
     */
    public function show($uuid)
    {
        $user = User::findByUuid($uuid);

        return $user;
    }
}

Customization

You can easily config the package for your needs by changing the column name and uuid version. For example:

<?php

//Create table
Schema::create('posts', function (Blueprint $table) {
    $table->uuid('universally_unique_id');
    $table->string('title');
    $table->timestamps();
});

//Eloquent Model
class Post extends Model
{
    use HasUuid;

    protected $uuidColumnName = 'universally_unique_id';
    protected $uuidVersion = 1;    // Available 1,3,4 or 5
    protected $uuidString  = '';   // Needed when $uuidVersion is "3 or 5"
}

Advance Customization

This package was built to be flexible and easy to customize!

You can use trait Uuidable to create your own trait with your custom code.

Methods

YourAppRocks\EloquentUuid\Traits\Uuidable;

getUuidColumnName() // Get the column name. ( default 'uuid' )
getUuid() // Get the uuid value.
setUuid($value) // Set the uuid value.
generateUuid() // Generate the UUID value. ( Using Ramsey\Uuid )
getUuidVersion() // Get uuid version or default to 4.
getUuidString() // Get string to generate uuid version 3 and 5.
validateUuidVersion() // Validate uuid version.

Example custom code

Replacing trait HasUuid for MyUuidTrait:

<?php

//Create table
Schema::create('users', function (Blueprint $table) {
    $table->uuid('uuid');
    $table->string('name');
    $table->timestamps();
});

//Create MyUuidTrait with custom code
use YourAppRocks\EloquentUuid\Traits\Uuidable;

trait MyUuidTrait
{
    use Uuidable;

    /**
     * Boot trait on the model.
     *
     * @return void
     */
    public static function bootMyUuidTrait()
    {
        static::creating(function ($model) {
            // My custom code here.
        });

        static::saving(function ($model) {
            // My custom code here.
        });
    }

    // My custom code here.
}

//Create Model
use MyUuidTrait;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    use MyUuidTrait;
}

Change log

Please see CHANGELOG for more information on what has changed recently.

Testing

$ composer test

Contributing

Please see CONTRIBUTING for details.

Credits

This package is inspired by this package.

License

The MIT License (MIT). Please see License File for more information.

mauro-pinheiro / eloquent-uuid

Maintainers

Details