[1.1] Feature/UUID v1 support (#6)

* Added support for UUIDv1

* Updated README

* Updated composer.json

* Closes #3

Author: matthew-inamdar

.gitignore

@@ -1,4 +1,5 @@
 /.idea
+/.php_cs.cache
 /.phpunit.result.cache
 
 # Created by https://www.gitignore.io/api/macos,phpstorm,composer,visualstudiocode

README.md

@@ -37,15 +37,25 @@
 
 ## Introduction
 
-A simple drop-in solution for providing UUIDv4 support for the IDs of your
+A simple drop-in solution for providing UUID support for the IDs of your
 Eloquent models.
 
+Both `v1` and `v4` IDs are supported out of the box, however should you need 
+`v3` or `v5` support, you can easily add this in.
+
 ## Installing
 
+Reference the table below for the correct version to use in conjunction with the
+version of Laravel you have installed:
+
+| Laravel | This package |
+| ------- | ------------ |
+| `v5.8.*` | `v1.*` |
+
 You can install the package via composer:
 
 ```bash
-composer require goldspecdigital/laravel-eloquent-uuid
+composer require goldspecdigital/laravel-eloquent-uuid:~v1.1
 ```
 
 ## Usage
@@ -90,8 +100,8 @@ class User extends Authenticatable
 
 ### Generating UUIDs
 
-If you don't specify the value for the primary key of your model, a UUIDv4 will
-be automatically generated. However, if you do specify your own UUIDv4 then it
+If you don't specify the value for the primary key of your model, a UUID will
+be automatically generated. However, if you do specify your own UUID then it
 will not generate one, but instead use the one you have explicitly provided. This
 can be useful when needing the know the ID of the model before you have created
 it:
@@ -106,6 +116,56 @@ $model = Model::create(['id' => '04d7f995-ef33-4870-a214-4e21c51ff76e']);
 echo $model->id; // 04d7f995-ef33-4870-a214-4e21c51ff76e
 ```
 
+### Specifying UUID versions
+
+By default, `v4` UUIDs will be used for your models. However, you can also 
+specify `v1` UUIDs to be used by setting the following property on your model:
+
+```php
+<?php
+
+namespace App\Models;
+
+use GoldSpecDigital\LaravelEloquentUUID\Database\Eloquent\Model;
+
+class BlogPost extends Model
+{
+    /**
+     * The UUID version to use.
+     *
+     * @var int
+     */
+    protected $uuidVersion = 1;
+}
+```
+
+#### Support for `v3` and `v5`
+
+Should you need support for `v3` or `v5` UUIDs, you can simply override the
+method which is responsible for generating the UUIDs:
+
+```php
+<?php
+
+namespace App\Models;
+
+use GoldSpecDigital\LaravelEloquentUUID\Database\Eloquent\Model;
+use Ramsey\Uuid\Uuid;
+
+class BlogPost extends Model
+{
+    /**
+     * @throws \Exception
+     * @return string
+     */
+    protected function generateUuid(): string
+    {
+        // UUIDv3 has been used here, but you can also use UUIDv5.
+        return Uuid::uuid3(Uuid::NAMESPACE_DNS, 'example.com')->toString();
+    }
+}
+```
+
 ## Running the tests
 
 To run the test suite you can use the following commands:

composer.json

@@ -1,6 +1,6 @@
 {
     "name": "goldspecdigital/laravel-eloquent-uuid",
-    "description": "A simple drop-in solution for providing UUIDv4 support for the IDs of your Eloquent models.",
+    "description": "A simple drop-in solution for providing UUID support for the IDs of your Eloquent models.",
     "type": "library",
     "license": "MIT",
     "keywords": [
@@ -41,11 +41,11 @@
     },
     "scripts": {
         "test": [
-            "@php vendor/bin/php-cs-fixer fix --config=.php_cs --allow-risky=yes --dry-run --diff --verbose --using-cache=no",
-            "@php vendor/bin/phpunit"
+            "@test:style",
+            "@test:unit"
         ],
-        "test:style": "@php vendor/bin/php-cs-fixer fix --config=.php_cs --allow-risky=yes --dry-run --diff --verbose --using-cache=no",
+        "test:style": "@php vendor/bin/php-cs-fixer fix --config=.php_cs --allow-risky=yes --dry-run --diff --verbose",
         "test:unit": "@php vendor/bin/phpunit",
-        "fix:style": "@php vendor/bin/php-cs-fixer fix --config=.php_cs --allow-risky=yes --diff --verbose --using-cache=no"
+        "fix:style": "@php vendor/bin/php-cs-fixer fix --config=.php_cs --allow-risky=yes --diff --verbose"
     }
 }

src/Database/Eloquent/Model.php

@@ -4,8 +4,9 @@
 
 namespace GoldSpecDigital\LaravelEloquentUUID\Database\Eloquent;
 
+use Exception;
 use Illuminate\Database\Eloquent\Model as BaseModel;
-use Illuminate\Support\Str;
+use Ramsey\Uuid\Uuid;
 
 abstract class Model extends BaseModel
 {
@@ -23,6 +24,13 @@ abstract class Model extends BaseModel
      */
     protected $keyIsUuid = true;
 
+    /**
+     * The UUID version to use.
+     *
+     * @var int
+     */
+    protected $uuidVersion = 4;
+
     /**
      * Indicates if the IDs are auto-incrementing.
      *
@@ -58,8 +66,24 @@ protected static function boot(): void
         static::creating(function (self $model): void {
             // Automatically generate a UUID if using them, and not provided.
             if ($model->keyIsUuid && empty($model->{$model->getKeyName()})) {
-                $model->{$model->getKeyName()} = Str::uuid()->toString();
+                $model->{$model->getKeyName()} = $model->generateUuid();
             }
         });
     }
+
+    /**
+     * @throws \Exception
+     * @return string
+     */
+    protected function generateUuid(): string
+    {
+        switch ($this->uuidVersion) {
+            case 1:
+                return Uuid::uuid1()->toString();
+            case 4:
+                return Uuid::uuid4()->toString();
+        }
+
+        throw new Exception("UUID version [{$this->uuidVersion}] not supported.");
+    }
 }

tests/Database/Eloquent/ModelWithUuidTest.php

@@ -4,28 +4,51 @@
 
 namespace GoldSpecDigital\LaravelEloquentUUID\Tests\Database\Eloquent;
 
-use GoldSpecDigital\LaravelEloquentUUID\Tests\Models\TestModelWithUuid;
+use GoldSpecDigital\LaravelEloquentUUID\Tests\Models\TestModelWithUuid1;
+use GoldSpecDigital\LaravelEloquentUUID\Tests\Models\TestModelWithUuid4;
 use GoldSpecDigital\LaravelEloquentUUID\Tests\TestCase;
 use Illuminate\Support\Str;
 
 class ModelWithUuidTest extends TestCase
 {
     /** @test */
-    public function it_generates_a_uuid_when_the_id_has_not_been_set(): void
+    public function it_generates_a_uuid1_when_the_id_has_not_been_set(): void
     {
-        /** @var \GoldSpecDigital\LaravelEloquentUUID\Tests\Models\TestModelWithUuid $testModel */
-        $testModel = TestModelWithUuid::query()->create();
+        /** @var \GoldSpecDigital\LaravelEloquentUUID\Tests\Models\TestModelWithUuid1 $testModel */
+        $testModel = TestModelWithUuid1::query()->create();
 
         $this->assertEquals(36, mb_strlen($testModel->id));
     }
 
     /** @test */
-    public function it_uses_the_uuid_provided_when_id_has_been_set(): void
+    public function it_generates_a_uuid4_when_the_id_has_not_been_set(): void
+    {
+        /** @var \GoldSpecDigital\LaravelEloquentUUID\Tests\Models\TestModelWithUuid4 $testModel */
+        $testModel = TestModelWithUuid4::query()->create();
+
+        $this->assertEquals(36, mb_strlen($testModel->id));
+    }
+
+    /** @test */
+    public function it_uses_the_uuid1_provided_when_id_has_been_set(): void
+    {
+        $uuid = Str::uuid()->toString();
+
+        /** @var \GoldSpecDigital\LaravelEloquentUUID\Tests\Models\TestModelWithUuid1 $testModel */
+        $testModel = TestModelWithUuid1::query()->create([
+            'id' => $uuid,
+        ]);
+
+        $this->assertEquals($uuid, $testModel->id);
+    }
+
+    /** @test */
+    public function it_uses_the_uuid4_provided_when_id_has_been_set(): void
     {
         $uuid = Str::uuid()->toString();
 
-        /** @var \GoldSpecDigital\LaravelEloquentUUID\Tests\Models\TestModelWithUuid $testModel */
-        $testModel = TestModelWithUuid::query()->create([
+        /** @var \GoldSpecDigital\LaravelEloquentUUID\Tests\Models\TestModelWithUuid4 $testModel */
+        $testModel = TestModelWithUuid4::query()->create([
             'id' => $uuid,
         ]);
 

tests/Database/Eloquent/ModelWithoutUuidTest.php

@@ -4,17 +4,26 @@
 
 namespace GoldSpecDigital\LaravelEloquentUUID\Tests\Database\Eloquent;
 
-use GoldSpecDigital\LaravelEloquentUUID\Tests\Models\TestModelWithoutUuid;
+use GoldSpecDigital\LaravelEloquentUUID\Tests\Models\TestModelWithoutUuid1;
+use GoldSpecDigital\LaravelEloquentUUID\Tests\Models\TestModelWithoutUuid4;
 use GoldSpecDigital\LaravelEloquentUUID\Tests\TestCase;
 use PDOException;
 
 class ModelWithoutUuidTest extends TestCase
 {
     /** @test */
-    public function it_does_not_generate_a_uuid_when_no_id_has_been_set(): void
+    public function it_does_not_generate_a_uuid1_when_no_id_has_been_set(): void
     {
         $this->expectException(PDOException::class);
 
-        TestModelWithoutUuid::query()->create();
+        TestModelWithoutUuid1::query()->create();
+    }
+
+    /** @test */
+    public function it_does_not_generate_a_uuid4_when_no_id_has_been_set(): void
+    {
+        $this->expectException(PDOException::class);
+
+        TestModelWithoutUuid4::query()->create();
     }
 }

tests/Models/TestModelWithUuid.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GoldSpecDigital\LaravelEloquentUUID\Tests\Models;
+
+use GoldSpecDigital\LaravelEloquentUUID\Database\Eloquent\Model;
+
+class TestModelWithUuid1 extends Model
+{
+    /**
+     * The table associated with the model.
+     *
+     * @var string
+     */
+    protected $table = 'test_model_with_uuids';
+
+    /**
+     * The UUID version to use.
+     *
+     * @var int
+     */
+    protected $uuidVersion = 1;
+}

tests/Models/TestModelWithUuid1.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GoldSpecDigital\LaravelEloquentUUID\Tests\Models;
+
+use GoldSpecDigital\LaravelEloquentUUID\Database\Eloquent\Model;
+
+class TestModelWithUuid4 extends Model
+{
+    /**
+     * The table associated with the model.
+     *
+     * @var string
+     */
+    protected $table = 'test_model_with_uuids';
+}

tests/Models/TestModelWithUuid4.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GoldSpecDigital\LaravelEloquentUUID\Tests\Models;
+
+use GoldSpecDigital\LaravelEloquentUUID\Database\Eloquent\Model;
+
+class TestModelWithoutUuid1 extends Model
+{
+    /**
+     * The table associated with the model.
+     *
+     * @var string
+     */
+    protected $table = 'test_model_without_uuids';
+
+    /**
+     * Indicates if the IDs are UUIDs.
+     *
+     * @var bool
+     */
+    protected $keyIsUuid = false;
+
+    /**
+     * The UUID version to use.
+     *
+     * @var int
+     */
+    protected $uuidVersion = 1;
+}