Add a description field for internal reference. (#9)

* Fix issue #8: Add a description field for internal reference.

* Switched the description field to string and updated project readme.

* Add runtime validation to description

---------

Co-authored-by: Ryan Chandler <ryangjchandler@gmail.com>

Author: Ojsholly

README.md

@@ -46,7 +46,7 @@ Alternatively, you can use the `RyanChandler\Bearer\Facades\Bearer` facade to `g
 ```php
 use RyanChandler\Bearer\Facades\Bearer;
 
-$token = Bearer::generate(domains: [], expiresAt: null);
+$token = Bearer::generate(domains: [], expiresAt: null, description: null);
 ```
 
 By default, Bearer uses time-ordered UUIDs for token strings. You can modify this behaviour by passing a `Closure` to `Bearer::generateTokenUsing`. This function must return a string for storage to the database.
@@ -61,7 +61,7 @@ Bearer::generateTokenUsing(static function (): string {
 
 ### Retrieving a `Token` instance
 
-To retreive a `Token` instance from the `token` string, you can use the `RyanChandler\Bearer\Facades\Bearer` facade.
+To retrieve a `Token` instance from the `token` string, you can use the `RyanChandler\Bearer\Facades\Bearer` facade.
 
 ```php
 use RyanChandler\Bearer\Facades\Bearer;
@@ -127,6 +127,21 @@ If you attempt to use this token from any domain other than `https://laravel.com
 
 > **Note**: domain checks include the scheme so be sure to add both cases for HTTP and HTTPS if needed.
 
+### Set a token description
+
+You can optionally set a description for the token. 
+
+```php
+$token = Bearer::find('my-token-string');
+
+$token->update([
+    'description' => 'Example description for the token.',
+]);
+```
+
+> **Note**: The description field accepts a maximum of 255 characters.
+
+
 ## Testing
 
 ```bash

database/factories/TokenFactory.php

@@ -29,6 +29,13 @@ public function domains($domains)
         ]);
     }
 
+    public function description(string $description)
+    {
+        return $this->state([
+            'description' => $description,
+        ]);
+    }
+
     public function definition()
     {
         return [

database/migrations/create_bearer_table.php.stub

@@ -11,6 +11,7 @@ return new class extends Migration
         Schema::create('bearer_tokens', function (Blueprint $table) {
             $table->id();
             $table->string('token')->unique();
+            $table->string('description')->nullable();
             $table->text('domains')->nullable();
             $table->datetime('expires_at')->nullable();
             $table->timestamps();

src/Bearer.php

@@ -34,13 +34,18 @@ public function generateTokenUsing(Closure $callback)
         return $this;
     }
 
-    public function generate(array $domains = [], DateTimeInterface $expiresAt = null): Token
+    public function generate(array $domains = [], ?DateTimeInterface $expiresAt = null, ?string $description = null): Token
     {
+        if ($description !== null && strlen($description) > 255) {
+            throw new \InvalidArgumentException('Token descriptions must be <= 255 characters.');
+        }
+
         $callback = $this->generateTokenCallback;
 
         return Token::create([
             'token' => $callback(),
             'domains' => $domains,
+            'description' => $description,
             'expires_at' => $expiresAt,
         ]);
     }

src/Models/Token.php

@@ -16,7 +16,7 @@ class Token extends Model
     protected $table = 'bearer_tokens';
 
     protected $fillable = [
-        'token', 'domains', 'expires_at',
+        'token', 'domains', 'description', 'expires_at',
     ];
 
     protected $casts = [
@@ -55,4 +55,12 @@ public function expires(DateTimeInterface $expiresAt): Token
 
         return $this;
     }
+
+    public function setDescription(string $description): Token
+    {
+        $this->description = $description;
+
+        return $this;
+    }
+
 }

tests/BearerTest.php

@@ -38,4 +38,16 @@ public function test_it_can_create_token_with_expires_at()
 
         $this->assertTrue($time->equalTo($token->expires_at));
     }
+
+    public function test_it_can_create_token_with_description()
+    {
+        $description = "Example description for the token.";
+
+        $token = Bearer::generate([], null, $description);
+
+        $this->assertDatabaseHas('bearer_tokens', [
+            'token' => $token->token,
+            'description' => $description,
+        ]);
+    }
 }

tests/TokenTest.php

@@ -117,4 +117,21 @@ public function test_it_can_interacts_with_expiration_time_in_months()
         $this->assertTrue($token->expired);
         Carbon::setTestNow();
     }
+
+    public function test_it_can_have_description()
+    {
+        $token = Token::factory()->create();
+
+        $description = 'Example description for the token.';
+
+        $token->setDescription($description);
+
+        $this->assertSame($description, $token->description);
+
+        $newDescription = 'New example description for the token.';
+
+        $token->update(['description' => $newDescription]);
+
+        $this->assertSame($newDescription, $token->description);
+    }
 }