feature/trait (#22)

* Added trait and tests

* Renamed tests

* Updated docs

* Bumped minor version in README

Author: matthew-inamdar

README.md

@@ -56,11 +56,17 @@ version of Laravel you have installed:
 You can install the package via composer:
 
 ```bash
-composer require goldspecdigital/laravel-eloquent-uuid:^v6.1
+composer require goldspecdigital/laravel-eloquent-uuid:^v6.2
 ```
 
 ## Usage
 
+There are two ways to use this package:
+1. By extending the provided model classes (preferred and simplest method).
+2. By using the provided model trait (allows for extending another model class).
+
+### Extending model
+
 When creating a Eloquent model, instead of extending the standard Laravel model
 class, extend from the model class provided by this package:
 
@@ -77,7 +83,7 @@ class BlogPost extends Model
 }
 ```
 
-### User model
+### Extending user model
 
 The User model that comes with a standard Laravel install has some extra
 configuration which is implemented in its parent class. This configuration only
@@ -99,13 +105,54 @@ class User extends Authenticatable
 }
 ```
 
+### Using trait
+
+As an alternative to extending the classes in the examples above, you also have
+the ability to use the provided trait instead. This requires a more involved
+setup process but allows you to extend your models from another class if needed:
+
+```php
+<?php
+
+namespace App\Models;
+
+use GoldSpecDigital\LaravelEloquentUUID\Database\Eloquent\Uuid;
+use Illuminate\Database\Eloquent\Model;
+
+class BlogPost extends Model
+{
+    use Uuid;
+    
+    /**
+     * The "type" of the auto-incrementing ID.
+     *
+     * @var string
+     */
+    protected $keyType = 'string';
+
+    /**
+     * Indicates if the IDs are auto-incrementing.
+     *
+     * @var bool
+     */
+    public $incrementing = false;
+
+    /**
+     * The attributes that are mass assignable.
+     *
+     * @var array
+     */
+    protected $guarded = [];
+}
+```
+
 ### Generating UUIDs
 
 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:
+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:
 
 ```php
 // No UUID provided (automatically generated).
@@ -120,7 +167,10 @@ 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:
+specify `v1` UUIDs to be used by setting the following property/method on your 
+model:
+
+#### When extending the class
 
 ```php
 <?php
@@ -140,6 +190,32 @@ class BlogPost extends Model
 }
 ```
 
+#### When using the trait
+
+```php
+<?php
+
+namespace App\Models;
+
+use GoldSpecDigital\LaravelEloquentUUID\Database\Eloquent\Uuid;
+use Illuminate\Database\Eloquent\Model;
+
+class BlogPost extends Model
+{
+    use Uuid;
+
+    /**
+     * The UUID version to use.
+     *
+     * @return int
+     */
+    protected function uuidVersion(): int
+    {
+        return 1;
+    }
+}
+```
+
 #### Support for `v3` and `v5`
 
 Should you need support for `v3` or `v5` UUIDs, you can simply override the

src/Database/Eloquent/Uuid.php

@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GoldSpecDigital\LaravelEloquentUUID\Database\Eloquent;
+
+use Exception;
+use Ramsey\Uuid\Uuid as RamseyUuid;
+
+trait Uuid
+{
+    /**
+     * Indicates if the IDs are UUIDs.
+     *
+     * @return bool
+     */
+    protected function keyIsUuid(): bool
+    {
+        return true;
+    }
+
+    /**
+     * The UUID version to use.
+     *
+     * @return int
+     */
+    protected function uuidVersion(): int
+    {
+        return 4;
+    }
+
+    /**
+     * The "booting" method of the model.
+     */
+    public static function bootUuid(): 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()} = $model->generateUuid();
+            }
+        });
+    }
+
+    /**
+     * @throws \Exception
+     * @return string
+     */
+    protected function generateUuid(): string
+    {
+        switch ($this->uuidVersion()) {
+            case 1:
+                return RamseyUuid::uuid1()->toString();
+            case 4:
+                return RamseyUuid::uuid4()->toString();
+        }
+
+        throw new Exception("UUID version [{$this->uuidVersion()}] not supported.");
+    }
+}

tests/Database/Eloquent/ModelExtendingClassWithUuidTest.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GoldSpecDigital\LaravelEloquentUUID\Tests\Database\Eloquent;
+
+use GoldSpecDigital\LaravelEloquentUUID\Tests\Models\TestModelExtendingClassWithUuid1;
+use GoldSpecDigital\LaravelEloquentUUID\Tests\Models\TestModelExtendingClassWithUuid4;
+use GoldSpecDigital\LaravelEloquentUUID\Tests\TestCase;
+use Illuminate\Support\Str;
+
+class ModelExtendingClassWithUuidTest extends TestCase
+{
+    /** @test */
+    public function it_generates_a_uuid1_when_the_id_has_not_been_set(): void
+    {
+        /** @var \GoldSpecDigital\LaravelEloquentUUID\Tests\Models\TestModelExtendingClassWithUuid1 $testModel */
+        $testModel = TestModelExtendingClassWithUuid1::query()->create();
+
+        $this->assertEquals(36, mb_strlen($testModel->id));
+    }
+
+    /** @test */
+    public function it_generates_a_uuid4_when_the_id_has_not_been_set(): void
+    {
+        /** @var \GoldSpecDigital\LaravelEloquentUUID\Tests\Models\TestModelExtendingClassWithUuid4 $testModel */
+        $testModel = TestModelExtendingClassWithUuid4::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\TestModelExtendingClassWithUuid1 $testModel */
+        $testModel = TestModelExtendingClassWithUuid1::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\TestModelExtendingClassWithUuid4 $testModel */
+        $testModel = TestModelExtendingClassWithUuid4::query()->create([
+            'id' => $uuid,
+        ]);
+
+        $this->assertEquals($uuid, $testModel->id);
+    }
+}

tests/Database/Eloquent/ModelExtendingClassWithoutUuidTest.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GoldSpecDigital\LaravelEloquentUUID\Tests\Database\Eloquent;
+
+use GoldSpecDigital\LaravelEloquentUUID\Tests\Models\TestModelExtendingClassWithoutUuid1;
+use GoldSpecDigital\LaravelEloquentUUID\Tests\Models\TestModelExtendingClassWithoutUuid4;
+use GoldSpecDigital\LaravelEloquentUUID\Tests\TestCase;
+use PDOException;
+
+class ModelExtendingClassWithoutUuidTest extends TestCase
+{
+    /** @test */
+    public function it_does_not_generate_a_uuid1_when_no_id_has_been_set(): void
+    {
+        $this->expectException(PDOException::class);
+
+        TestModelExtendingClassWithoutUuid1::query()->create();
+    }
+
+    /** @test */
+    public function it_does_not_generate_a_uuid4_when_no_id_has_been_set(): void
+    {
+        $this->expectException(PDOException::class);
+
+        TestModelExtendingClassWithoutUuid4::query()->create();
+    }
+}

tests/Database/Eloquent/ModelWithUuidTest.php renamed to tests/Database/Eloquent/ModelUsingTraitWithUuidTest.php

@@ -4,27 +4,27 @@
 
 namespace GoldSpecDigital\LaravelEloquentUUID\Tests\Database\Eloquent;
 
-use GoldSpecDigital\LaravelEloquentUUID\Tests\Models\TestModelWithUuid1;
-use GoldSpecDigital\LaravelEloquentUUID\Tests\Models\TestModelWithUuid4;
+use GoldSpecDigital\LaravelEloquentUUID\Tests\Models\TestModelUsingTraitWithUuid1;
+use GoldSpecDigital\LaravelEloquentUUID\Tests\Models\TestModelUsingTraitWithUuid4;
 use GoldSpecDigital\LaravelEloquentUUID\Tests\TestCase;
 use Illuminate\Support\Str;
 
-class ModelWithUuidTest extends TestCase
+class ModelUsingTraitWithUuidTest extends TestCase
 {
     /** @test */
     public function it_generates_a_uuid1_when_the_id_has_not_been_set(): void
     {
-        /** @var \GoldSpecDigital\LaravelEloquentUUID\Tests\Models\TestModelWithUuid1 $testModel */
-        $testModel = TestModelWithUuid1::query()->create();
+        /** @var \GoldSpecDigital\LaravelEloquentUUID\Tests\Models\TestModelUsingTraitWithUuid1 $testModel */
+        $testModel = TestModelUsingTraitWithUuid1::query()->create();
 
         $this->assertEquals(36, mb_strlen($testModel->id));
     }
 
     /** @test */
     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();
+        /** @var \GoldSpecDigital\LaravelEloquentUUID\Tests\Models\TestModelUsingTraitWithUuid4 $testModel */
+        $testModel = TestModelUsingTraitWithUuid4::query()->create();
 
         $this->assertEquals(36, mb_strlen($testModel->id));
     }
@@ -34,8 +34,8 @@ 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([
+        /** @var \GoldSpecDigital\LaravelEloquentUUID\Tests\Models\TestModelUsingTraitWithUuid1 $testModel */
+        $testModel = TestModelUsingTraitWithUuid1::query()->create([
             'id' => $uuid,
         ]);
 
@@ -47,8 +47,8 @@ public function it_uses_the_uuid4_provided_when_id_has_been_set(): void
     {
         $uuid = Str::uuid()->toString();
 
-        /** @var \GoldSpecDigital\LaravelEloquentUUID\Tests\Models\TestModelWithUuid4 $testModel */
-        $testModel = TestModelWithUuid4::query()->create([
+        /** @var \GoldSpecDigital\LaravelEloquentUUID\Tests\Models\TestModelUsingTraitWithUuid4 $testModel */
+        $testModel = TestModelUsingTraitWithUuid4::query()->create([
             'id' => $uuid,
         ]);
 

tests/Database/Eloquent/ModelWithoutUuidTest.php renamed to tests/Database/Eloquent/ModelUsingTraitWithoutUuidTest.php

@@ -4,26 +4,26 @@
 
 namespace GoldSpecDigital\LaravelEloquentUUID\Tests\Database\Eloquent;
 
-use GoldSpecDigital\LaravelEloquentUUID\Tests\Models\TestModelWithoutUuid1;
-use GoldSpecDigital\LaravelEloquentUUID\Tests\Models\TestModelWithoutUuid4;
+use GoldSpecDigital\LaravelEloquentUUID\Tests\Models\TestModelUsingTraitWithoutUuid1;
+use GoldSpecDigital\LaravelEloquentUUID\Tests\Models\TestModelUsingTraitWithoutUuid4;
 use GoldSpecDigital\LaravelEloquentUUID\Tests\TestCase;
 use PDOException;
 
-class ModelWithoutUuidTest extends TestCase
+class ModelUsingTraitWithoutUuidTest extends TestCase
 {
     /** @test */
     public function it_does_not_generate_a_uuid1_when_no_id_has_been_set(): void
     {
         $this->expectException(PDOException::class);
 
-        TestModelWithoutUuid1::query()->create();
+        TestModelUsingTraitWithoutUuid1::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();
+        TestModelUsingTraitWithoutUuid4::query()->create();
     }
 }

tests/Models/TestModelWithUuid1.php renamed to tests/Models/TestModelExtendingClassWithUuid1.php

@@ -6,7 +6,7 @@
 
 use GoldSpecDigital\LaravelEloquentUUID\Database\Eloquent\Model;
 
-class TestModelWithUuid1 extends Model
+class TestModelExtendingClassWithUuid1 extends Model
 {
     /**
      * The table associated with the model.
@@ -15,6 +15,7 @@ class TestModelWithUuid1 extends Model
      */
     protected $table = 'test_model_with_uuids';
 
+
     /**
      * The UUID version to use.
      *

tests/Models/TestModelWithUuid4.php renamed to tests/Models/TestModelExtendingClassWithUuid4.php

@@ -6,7 +6,7 @@
 
 use GoldSpecDigital\LaravelEloquentUUID\Database\Eloquent\Model;
 
-class TestModelWithUuid4 extends Model
+class TestModelExtendingClassWithUuid4 extends Model
 {
     /**
      * The table associated with the model.