Merge pull request #225 from stevebauman/master

Add ability to tap `ShortURL` model before creation

README.md

@@ -28,6 +28,7 @@
             - [Tracking Operating System & Operating System Version](#tracking-operating-system--operating-system-version)
             - [Tracking Device Type](#tracking-device-type)
             - [Tracking Referer URL](#tracking-referer-url)
+        - [Custom Short URL Fields](#custom-short-url-fields)
         - [Single Use](#single-use)
         - [Enforce HTTPS](#enforce-https)
         - [Forwarding Query Parameters](#forwarding-query-parameters)
@@ -235,6 +236,26 @@ $builder = new \AshAllenDesign\ShortURL\Classes\Builder();
 $shortURLObject = $builder->destinationUrl('https://destination.com')->trackVisits()->trackRefererURL()->make();
 ```
 
+#### Custom Short URL Fields
+
+There may be times when you want to add your own custom fields to the ShortURL model and store them in the database. For example, you might want to associate the short URL with a tenant, organisation, user, etc.
+
+To do this you can use the `beforeCreate` method when building your short URL. This method accepts a closure that receives the `AshAllenDesign\ShortURL\Models\ShortURL` model instance before it's saved to your database.
+
+The example below shows how to add a `tenant_id` field to the `AshAllenDesign\ShortURL\Models\ShortURL` model:
+
+```php
+$tenantId = 123;
+
+$shortURL = ShortUrlBuilder::destinationUrl($url)
+    ->beforeCreate(function (ShortURL $model): void {
+        $model->tenant_id = $tenantId;
+    })
+    )->make();
+```
+
+Please remember that to store custom fields in the database, you'll have to make sure those fields are added to the `short_urls` table. You can do this by creating a new migration that adds the fields to the table, or by updating the migrations that ship with this package.
+
 #### Single Use
 By default, all of the shortened URLs can be visited for as long as you leave them available. However, you may want to
 only allow access to a shortened URL once. Then any visitors who visit the URL after it has already been viewed will

src/Classes/Builder.php

@@ -7,6 +7,7 @@
 use AshAllenDesign\ShortURL\Exceptions\ValidationException;
 use AshAllenDesign\ShortURL\Models\ShortURL;
 use Carbon\Carbon;
+use Closure;
 use Illuminate\Support\Facades\Route;
 use Illuminate\Support\Str;
 use Illuminate\Support\Traits\Conditionable;
@@ -161,6 +162,14 @@ class Builder
      */
     protected ?int $generateKeyUsing = null;
 
+    /**
+     * Define a callback to access the ShortURL
+     * model prior to creation.
+     *
+     * @var Closure|null
+     */
+    protected ?Closure $beforeCreateCallback = null;
+
     /**
      * Builder constructor.
      *
@@ -488,13 +497,32 @@ public function deactivateAt(Carbon $deactivationTime): self
         return $this;
     }
 
+    /**
+     * Set the seed to be used when generating a short URL key.
+     *
+     * @param  int  $generateUsing
+     * @return $this
+     */
     public function generateKeyUsing(int $generateUsing): self
     {
         $this->generateKeyUsing = $generateUsing;
 
         return $this;
     }
 
+    /**
+     * Pass the Short URL model into the callback before it is created.
+     *
+     * @param  Closure  $callback
+     * @return $this
+     */
+    public function beforeCreate(Closure $callback): self
+    {
+        $this->beforeCreateCallback = $callback;
+
+        return $this;
+    }
+
     /**
      * Attempt to build a shortened URL and return it.
      *
@@ -512,7 +540,13 @@ public function make(): ShortURL
 
         $this->checkKeyDoesNotExist();
 
-        $shortURL = ShortURL::create($data);
+        $shortURL = new ShortURL($data);
+
+        if ($this->beforeCreateCallback) {
+            value($this->beforeCreateCallback, $shortURL);
+        }
+
+        $shortURL->save();
 
         $this->resetOptions();
 
@@ -655,6 +689,11 @@ public function resetOptions(): self
         $this->trackRefererURL = null;
         $this->trackDeviceType = null;
 
+        $this->activateAt = null;
+        $this->deactivateAt = null;
+        $this->generateKeyUsing = null;
+        $this->beforeCreateCallback = null;
+
         return $this;
     }
 

tests/Unit/Classes/BuilderTest.php

@@ -549,6 +549,19 @@ public function data_can_be_set_on_the_builder_using_when(bool $flag, string $de
         $this->assertSame($destination, $shortUrl->destination_url);
     }
 
+    /** @test */
+    public function data_can_be_overridden_on_model_using_make_callback(): void
+    {
+        $shortUrl = (new Builder())
+            ->destinationUrl('https://foo.com')
+            ->beforeCreate(function (ShortURL $shortURL) {
+                $shortURL->destination_url = 'https://bar.com';
+            })
+            ->make();
+
+        $this->assertSame('https://bar.com', $shortUrl->destination_url);
+    }
+
     /** @test */
     public function app_url_is_set_if_the_default_url_config_value_is_not_set(): void
     {