├── CHANGELOG.md ├── LICENSE.md ├── README.md ├── composer.json └── src ├── Exceptions ├── InvalidUuidVersionException.php └── MissingUuidColumnException.php └── Traits ├── HasUuid.php └── Uuidable.php /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | All Notable changes to `your-app-rocks/eloquent-uuid` will be documented in this file. This project adheres to [Semantic Versioning](http://semver.org/). 4 | 5 | The format is based on [Keep a Changelog](http://keepachangelog.com/). 6 | 7 | ## [Unreleased] 8 | 9 | ## [2.5.0] - 2021-02-24 10 | ### Updated 11 | 12 | - Add support PHP 8 | Fixing "Update for php 8" ([#9](https://github.com/YourAppRocks/eloquent-uuid/issues/9)) 13 | - Tests against PHP 8 14 | 15 | ## [2.4.0] - 2020-09-08 16 | ### Updated 17 | 18 | - Update require-dev constraints: 19 | - Add `orchestra/testbench` **^6.0** (Required to run tests against Laravel ^8.0) 20 | - Update .gitignore 21 | 22 | ## [2.3.0] - 2020-07-24 23 | ### Added 24 | 25 | - Support multiple connections ([#8](https://github.com/YourAppRocks/eloquent-uuid/pull/8)) 26 | 27 | ## [2.2.0] - 2020-04-20 28 | ### Updated 29 | 30 | - Fixing "Laravel 7 : composer don't allow install" ([#5](https://github.com/YourAppRocks/eloquent-uuid/issues/5)) 31 | - Bump `ramsey/uuid` **^4.0** 32 | 33 | ## [2.1.0] - 2020-04-19 34 | ### Updated 35 | 36 | - Bump `ramsey/uuid` **^3.9** 37 | - Tests against PHP 7.4 38 | - Update require-dev constraints: 39 | - Add `orchestra/testbench` **^5.0** (Required to run tests against Laravel ^7.0) 40 | - Add `phpunit/phpunit` **^9.0** 41 | 42 | ### Removed 43 | 44 | - Remove 'check-style' script in `.travis.yml` file 45 | 46 | ## [2.0.1] - 2019-09-08 47 | ### Updated 48 | 49 | - Update `TestCase.php`: The `setUp()` method now return void type. 50 | - Update require-dev constraints: 51 | - Drop `phpunit/phpunit` **^6.0** (Support only PHP <7.0) 52 | - Add `orchestra/testbench` **^4.0** (Required to run tests against Laravel ^6.0) 53 | - Fix php files permission. 54 | 55 | ## [2.0] - 2019-05-05 56 | ### Updated 57 | 58 | - Fixing "Class was composed in Model" ([#1](https://github.com/YourAppRocks/eloquent-uuid/issues/1)) 59 | - **Breaking Change**: `Uuidable` trait: Replaced trait properties ( *$uuidColumnName*, *$uuidVersion* and *$uuidString* ) by 'get' methods with return default value 60 | - **Breaking Change**: `Uuidable` trait: `generateUuid()` method now throws `InvalidUuidVersionException` instead of `InvalidArgumentException` 61 | - **Breaking Change**: `Uuidable` trait: `validateUuidVersion()` method now has visibility `public` instead of `private` 62 | - Refactored all tests 63 | 64 | ### Removed 65 | 66 | - **Breaking Change**: `Uuidable` trait: Removeded `setUuidColumnName()`, `setUuidVersion()` and `setUuidString()` methods. 67 | 68 | 69 | ## [1.2.2] - 2019-02-13 70 | ### Added 71 | - Tests against PHP 7.3 72 | 73 | ### Updated 74 | - Updated dependencies 75 | 76 | ## [1.2.1] - 2018-05-31 77 | ### Added 78 | - Add 'check-style' composer script. 79 | 80 | ## [1.2.0] - 2018-04-30 81 | ### Added 82 | - Add 'findByUuid()' scope query. 83 | 84 | ## [1.1.0] - 2018-04-29 85 | ### Added 86 | - Add support for the custom key name model binding. [See Laravel Documentation](https://laravel.com/docs/5.7/routing#route-model-binding) 87 | 88 | ## 1.0.0 - 2018-03-25 89 | ### Added 90 | - First Release 91 | 92 | [Unreleased]: https://github.com/YourAppRocks/eloquent-uuid/compare/2.5.0...HEAD 93 | 94 | [2.5.0]: https://github.com/YourAppRocks/eloquent-uuid/compare/2.5.0...2.4.0 95 | [2.4.0]: https://github.com/YourAppRocks/eloquent-uuid/compare/2.4.0...2.3.0 96 | [2.3.0]: https://github.com/YourAppRocks/eloquent-uuid/compare/2.3.0...2.2.0 97 | [2.2.0]: https://github.com/YourAppRocks/eloquent-uuid/compare/2.2.0...2.1.0 98 | [2.1.0]: https://github.com/YourAppRocks/eloquent-uuid/compare/2.1.0...2.0.1 99 | [2.0.1]: https://github.com/YourAppRocks/eloquent-uuid/compare/2.0.1...2.0 100 | [2.0]: https://github.com/YourAppRocks/eloquent-uuid/compare/1.2.2...2.0 101 | [1.2.2]: https://github.com/YourAppRocks/eloquent-uuid/compare/1.2.1...1.2.2 102 | [1.2.1]: https://github.com/YourAppRocks/eloquent-uuid/compare/1.2.0...1.2.1 103 | [1.2.0]: https://github.com/YourAppRocks/eloquent-uuid/compare/1.1.0...1.2.0 104 | [1.1.0]: https://github.com/YourAppRocks/eloquent-uuid/compare/1.0.0...1.1.0 105 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | # The MIT License (MIT) 2 | 3 | Copyright (c) YourApp.Rocks 4 | 5 | > Permission is hereby granted, free of charge, to any person obtaining a copy 6 | > of this software and associated documentation files (the "Software"), to deal 7 | > in the Software without restriction, including without limitation the rights 8 | > to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | > copies of the Software, and to permit persons to whom the Software is 10 | > furnished to do so, subject to the following conditions: 11 | > 12 | > The above copyright notice and this permission notice shall be included in 13 | > all copies or substantial portions of the Software. 14 | > 15 | > THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | > IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | > FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | > AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | > LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | > OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 21 | > THE SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 |

2 | YourApp.Rocks logo 3 |

4 | 5 | 6 | # Eloquent UUID 7 | 8 | [![Software License][ico-license]](LICENSE.md) 9 | [![Build Status][ico-build]][link-build] 10 | [![Latest Stable Version][ico-stable]][link-stable] 11 | [![Total Downloads][ico-downloads]][link-downloads] 12 | 13 | Simple and flexible Laravel package that adds support for UUID generation automatically for any Eloquent model. 14 | 15 | * Generate `uuid` automatically. 16 | * Choose a custom name for the `uuid` column in your table. *(default 'uuid')* 17 | * Choose the version of the generated uuid. *(default '4')* 18 | * Checks for `uuid version` and `column name`. *(throws the InvalidUuidVersionException and MissingUuidColumnException exceptions)* 19 | * Prevents update on uuid value. 20 | 21 | ### What is a UUID? 22 | 23 | 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. 24 | For example:`123E4567-E89b-12D3-A456-426655440000` containing letters and numbers. that will uniquely identify something. you can read more [here](https://en.wikipedia.org/wiki/Universally_unique_identifier). 25 | 26 | ## Installation 27 | 28 | You can install the package via Composer: 29 | 30 | ``` bash 31 | composer require your-app-rocks/eloquent-uuid 32 | ``` 33 | 34 | or via `composer.json` file 35 | 36 | ```json 37 | { 38 | "require": { 39 | "your-app-rocks/eloquent-uuid": "~2" 40 | } 41 | } 42 | ``` 43 | 44 | ## Usage 45 | 46 | ### Create table 47 | 48 | Create your table with a `uuid` column. For example: 49 | 50 | ```php 51 | uuid('uuid'); 55 | $table->string('name'); 56 | $table->timestamps(); 57 | }); 58 | ``` 59 | ### Create model 60 | 61 | In your eloquent model, add trait ``HasUuid``: 62 | 63 | ```php 64 | all()); // Automatically generate a uuid 96 | 97 | return $user->getUuid() // Return UUID value. 98 | } 99 | 100 | /** 101 | * Get User by custom 'UUID' key name - Implicit Binding. 102 | * See https://laravel.com/docs/5.8/routing#route-model-binding 103 | * 104 | * @param User $user 105 | * @return void 106 | */ 107 | public function show(User $user) 108 | { 109 | return $user; 110 | } 111 | 112 | //OR 113 | 114 | /** 115 | * Get User by scope query. 116 | */ 117 | public function show($uuid) 118 | { 119 | $user = User::findByUuid($uuid); 120 | 121 | return $user; 122 | } 123 | } 124 | ``` 125 | 126 | ## Customization 127 | 128 | You can easily config the package for your needs by changing the *column name* and *uuid version*. For example: 129 | 130 | ```php 131 | uuid('universally_unique_id'); 136 | $table->string('title'); 137 | $table->timestamps(); 138 | }); 139 | 140 | //Eloquent Model 141 | class Post extends Model 142 | { 143 | use HasUuid; 144 | 145 | protected $uuidColumnName = 'universally_unique_id'; 146 | protected $uuidVersion = 1; // Available 1,3,4 or 5 147 | protected $uuidString = ''; // Needed when $uuidVersion is "3 or 5" 148 | } 149 | ``` 150 | ## Advance Customization 151 | 152 | This package was built to be flexible and easy to customize! 153 | 154 | You can use trait ``Uuidable`` to create your own trait with your custom code. 155 | 156 | ### Methods 157 | 158 | #### YourAppRocks\EloquentUuid\Traits\Uuidable; 159 | 160 | - getUuidColumnName() ``// Get the column name. ( default 'uuid' )`` 161 | - getUuid() ``// Get the uuid value.`` 162 | - setUuid($value) ``// Set the uuid value.`` 163 | - generateUuid() ``// Generate the UUID value. ( Using Ramsey\Uuid )`` 164 | - getUuidVersion() ``// Get uuid version or default to 4.`` 165 | - getUuidString() ``// Get string to generate uuid version 3 and 5.`` 166 | - validateUuidVersion() ``// Validate uuid version.`` 167 | 168 | ### Example custom code 169 | 170 | Replacing trait ``HasUuid`` for ``MyUuidTrait``: 171 | 172 | 173 | ```php 174 | uuid('uuid'); 179 | $table->string('name'); 180 | $table->timestamps(); 181 | }); 182 | 183 | //Create MyUuidTrait with custom code 184 | use YourAppRocks\EloquentUuid\Traits\Uuidable; 185 | 186 | trait MyUuidTrait 187 | { 188 | use Uuidable; 189 | 190 | /** 191 | * Boot trait on the model. 192 | * 193 | * @return void 194 | */ 195 | public static function bootMyUuidTrait() 196 | { 197 | static::creating(function ($model) { 198 | // My custom code here. 199 | }); 200 | 201 | static::saving(function ($model) { 202 | // My custom code here. 203 | }); 204 | } 205 | 206 | // My custom code here. 207 | } 208 | 209 | //Create Model 210 | use MyUuidTrait; 211 | use Illuminate\Database\Eloquent\Model; 212 | 213 | class User extends Model 214 | { 215 | use MyUuidTrait; 216 | } 217 | 218 | ``` 219 | ## Change log 220 | 221 | Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. 222 | 223 | ## Testing 224 | 225 | ``` bash 226 | $ composer test 227 | ``` 228 | 229 | ## Contributing 230 | 231 | Please see [CONTRIBUTING](CONTRIBUTING.md) for details. 232 | 233 | ## Credits 234 | 235 | - [João Roberto][link-author] 236 | - [All Contributors][link-contributors] 237 | 238 | This package is inspired by [this][link-inspire] package. 239 | 240 | ## License 241 | 242 | The MIT License (MIT). Please see [License File](LICENSE.md) for more information. 243 | 244 | [ico-build]: https://travis-ci.org/YourAppRocks/eloquent-uuid.svg?branch=master 245 | [ico-downloads]: https://poser.pugx.org/your-app-rocks/eloquent-uuid/downloads 246 | [ico-license]: https://img.shields.io/badge/license-MIT-brightgreen.svg 247 | [ico-stable]: https://poser.pugx.org/your-app-rocks/eloquent-uuid/v/stable 248 | 249 | [link-author]: https://github.com/joaorobertopb 250 | [link-build]: https://travis-ci.org/YourAppRocks/eloquent-uuid 251 | [link-contributors]: ../../contributors 252 | [link-downloads]: https://packagist.org/packages/your-app-rocks/eloquent-uuid 253 | [link-inspire]: https://github.com/kblais/laravel-uuid/ 254 | [link-stable]: https://packagist.org/packages/your-app-rocks/eloquent-uuid 255 | 256 | -------------------------------------------------------------------------------- /composer.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "your-app-rocks/eloquent-uuid", 3 | "type": "library", 4 | "description": "Adds support for UUID generation automatically for Models Eloquents.", 5 | "keywords": [ 6 | "YourApp.Rocks", 7 | "uuid", 8 | "eloquent-uuid", 9 | "universal unique id" 10 | ], 11 | "homepage": "https://yourapp.rocks", 12 | "license": "MIT", 13 | "authors": [ 14 | { 15 | "name": "João Roberto P. Borges", 16 | "email": "joaorobertopb@gmail.com" 17 | } 18 | ], 19 | "require": { 20 | "php": "^7.1 || ^8.0", 21 | "ramsey/uuid": "^3.9 || ^4.0" 22 | }, 23 | "require-dev": { 24 | "orchestra/testbench": "^3.5 || ^4.0 || ^5.0 || ^6.0", 25 | "phpunit/phpunit": "^7.0 || ^8.0 || ^9.0", 26 | "friendsofphp/php-cs-fixer": "^2.16" 27 | }, 28 | "autoload": { 29 | "psr-4": { 30 | "YourAppRocks\\EloquentUuid\\": "src/" 31 | } 32 | }, 33 | "autoload-dev": { 34 | "psr-4": { 35 | "YourAppRocks\\EloquentUuid\\Tests\\": "tests/" 36 | } 37 | }, 38 | "scripts": { 39 | "test": "phpunit", 40 | "check-style": "php-cs-fixer fix --using-cache=no --diff --dry-run .", 41 | "fix-style": "php-cs-fixer --using-cache=no fix ." 42 | }, 43 | "scripts-descriptions": { 44 | "test": "Run all tests.", 45 | "check-style": "Run style checks (only dry run - no fixing!).", 46 | "fix-style": "Run style checks and fix violations." 47 | }, 48 | "config": { 49 | "sort-packages": true 50 | } 51 | } 52 | -------------------------------------------------------------------------------- /src/Exceptions/InvalidUuidVersionException.php: -------------------------------------------------------------------------------- 1 | 7 | * 8 | * This source file is subject to the license file that is bundled 9 | * with this source code in the file LICENSE. 10 | */ 11 | 12 | namespace YourAppRocks\EloquentUuid\Exceptions; 13 | 14 | class InvalidUuidVersionException extends \InvalidArgumentException 15 | { 16 | protected $message = 'Invalid value! Expected 1,3,4 or 5 integer values.'; 17 | } 18 | -------------------------------------------------------------------------------- /src/Exceptions/MissingUuidColumnException.php: -------------------------------------------------------------------------------- 1 | 7 | * 8 | * This source file is subject to the license file that is bundled 9 | * with this source code in the file LICENSE. 10 | */ 11 | 12 | namespace YourAppRocks\EloquentUuid\Exceptions; 13 | 14 | class MissingUuidColumnException extends \Exception 15 | { 16 | } 17 | -------------------------------------------------------------------------------- /src/Traits/HasUuid.php: -------------------------------------------------------------------------------- 1 | 7 | * 8 | * This source file is subject to the license file that is bundled 9 | * with this source code in the file LICENSE. 10 | */ 11 | 12 | namespace YourAppRocks\EloquentUuid\Traits; 13 | 14 | use Illuminate\Database\Eloquent\ModelNotFoundException; 15 | use Ramsey\Uuid\Uuid as RamseyUuid; 16 | use YourAppRocks\EloquentUuid\Exceptions\MissingUuidColumnException; 17 | 18 | trait HasUuid 19 | { 20 | use Uuidable; 21 | 22 | /** 23 | * Boot trait on the model. 24 | * 25 | * @return void 26 | */ 27 | public static function bootHasUuid() 28 | { 29 | static::creating(function ($model) { 30 | (new static)->hasColumnUuid($model); 31 | 32 | $model->setUuid($model->generateUuid()); 33 | }); 34 | 35 | static::saving(function ($model) { 36 | (new static)->hasColumnUuid($model); 37 | 38 | $originalUuid = $model->getOriginal($model->getUuidColumnName()); 39 | 40 | if ($originalUuid !== $model->getUuid()) { 41 | $model->setUuid($originalUuid); 42 | } 43 | }); 44 | } 45 | 46 | /** 47 | * Get the route key for the model. 48 | * 49 | * @return string 50 | */ 51 | public function getRouteKeyName() 52 | { 53 | return $this->getUuidColumnName(); 54 | } 55 | 56 | /** 57 | * Scope query by UUID. 58 | * 59 | * @param string $uuid 60 | * @param bool $firstOrFail 61 | * @return \Illuminate\Database\Eloquent\Model|\Illuminate\Database\Eloquent\Builder 62 | * 63 | * @throws \Illuminate\Database\Eloquent\ModelNotFoundException 64 | */ 65 | public function scopeFindByUuid($query, $uuid, $firstOrFail = true) 66 | { 67 | $this->validateUuid($uuid); 68 | 69 | $queryBuilder = $query->where($this->getUuidColumnName(), $uuid); 70 | 71 | return $firstOrFail ? $queryBuilder->firstOrFail() : $queryBuilder; 72 | } 73 | 74 | /** 75 | * Check if the table have a column uuid. 76 | * 77 | * @param \Illuminate\Database\Eloquent\Model 78 | * @return void 79 | * 80 | * @throws \YourAppRocks\EloquentUuid\Exceptions\MissingUuidColumnException 81 | */ 82 | private function hasColumnUuid($model) 83 | { 84 | if (! $model->getConnection()->getSchemaBuilder()->hasColumn($model->getTable(), $model->getUuidColumnName())) { 85 | throw new MissingUuidColumnException("You don't have a '{$model->getUuidColumnName()}' column on '{$model->getTable()}' table."); 86 | } 87 | } 88 | 89 | /** 90 | * Check if uuid value is valid. 91 | * 92 | * @param string $uuid 93 | * @return void 94 | * 95 | * @throws \Illuminate\Database\Eloquent\ModelNotFoundException 96 | */ 97 | private function validateUuid($uuid) 98 | { 99 | if (! RamseyUuid::isValid($uuid)) { 100 | throw (new ModelNotFoundException)->setModel(get_class($this)); 101 | } 102 | } 103 | } 104 | -------------------------------------------------------------------------------- /src/Traits/Uuidable.php: -------------------------------------------------------------------------------- 1 | 7 | * 8 | * This source file is subject to the license file that is bundled 9 | * with this source code in the file LICENSE. 10 | */ 11 | 12 | namespace YourAppRocks\EloquentUuid\Traits; 13 | 14 | use Ramsey\Uuid\Uuid as RamseyUuid; 15 | use YourAppRocks\EloquentUuid\Exceptions\InvalidUuidVersionException; 16 | 17 | trait Uuidable 18 | { 19 | /** 20 | * Get the column name for the "uuid". 21 | * 22 | * @return string 23 | */ 24 | public function getUuidColumnName() 25 | { 26 | return property_exists($this, 'uuidColumnName') ? $this->uuidColumnName : 'uuid'; 27 | } 28 | 29 | /** 30 | * Get "uuid" version or default to 4. 31 | * 32 | * @return int 33 | */ 34 | public function getUuidVersion() 35 | { 36 | return property_exists($this, 'uuidVersion') ? $this->uuidVersion : 4; 37 | } 38 | 39 | /** 40 | * Get string to generate uuid version 3 and 5. 41 | * 42 | * @return string 43 | */ 44 | public function getUuidString() 45 | { 46 | return property_exists($this, 'uuidString') ? $this->uuidString : ''; 47 | } 48 | 49 | /** 50 | * Get the uuid value. 51 | * 52 | * @return string|null 53 | */ 54 | public function getUuid() 55 | { 56 | if (! empty($this->getUuidColumnName())) { 57 | return (string) $this->{$this->getUuidColumnName()}; 58 | } 59 | } 60 | 61 | /** 62 | * Set the uuid value. 63 | * 64 | * @param string $value 65 | * @return void 66 | */ 67 | public function setUuid($value) 68 | { 69 | if (! empty($this->getUuidColumnName())) { 70 | $this->{$this->getUuidColumnName()} = $value; 71 | } 72 | } 73 | 74 | /** 75 | * Generate the UUID. 76 | * 77 | * @return string 78 | * @throws InvalidUuidVersionException 79 | */ 80 | public function generateUuid() 81 | { 82 | switch ($this->getUuidVersion()) { 83 | case 1: 84 | return RamseyUuid::uuid1()->toString(); 85 | case 3: 86 | return RamseyUuid::uuid3(RamseyUuid::NAMESPACE_DNS, $this->getUuidString())->toString(); 87 | case 4: 88 | return RamseyUuid::uuid4()->toString(); 89 | case 5: 90 | return RamseyUuid::uuid5(RamseyUuid::NAMESPACE_DNS, $this->getUuidString())->toString(); 91 | default: 92 | throw new InvalidUuidVersionException; 93 | } 94 | } 95 | 96 | /** 97 | * Validate uuid version. 98 | * 99 | * @throws InvalidUuidVersionException 100 | */ 101 | public function validateUuidVersion($value) 102 | { 103 | $validValues = [1, 3, 4, 5]; 104 | 105 | if (! in_array($value, $validValues)) { 106 | throw new InvalidUuidVersionException(); 107 | } 108 | } 109 | } 110 | --------------------------------------------------------------------------------