Add generating-order-number hook (#97)

Author: duncanmcclean

docs/docs/orders.md

@@ -133,6 +133,60 @@ You may provide a `limit` option to control the number of items displayed in lis
 ['type' => 'recent_orders', 'width' => 50, 'limit' => 10],
 ```
 
+## Order Numbers
+
+When an order is created, Cargo will generate a unique order number. By default, order numbers start at `1000` but the minimum value is configurable:
+
+```php
+// config/statamic/cargo.php
+
+'minimum_order_number' => 5000,
+```
+
+You may hook into the Stache `OrderRepository` class to customize how order numbers are generated:
+
+```php
+// app/Providers/AppServiceProvider.php
+
+use DuncanMcClean\Cargo\Stache\Repositories\OrderRepository;
+
+OrderRepository::hook('generating-order-number', function ($payload, $next) {
+    // $payload->order;
+    // $payload->orderNumber;
+    
+    $payload->orderNumber = 5000;
+    
+    return $next($payload);
+});
+```
+
+:::tip note
+When storing orders in the database, the `order_number` column is auto-incrementing, meaning the database (eg. MySQL, PostgreSQL, etc) is in charge of generating the next order number.
+
+To customize how order numbers are generated, remove `->autoIncrement()` from the migration and listen for the Order model's `creating` event:
+
+```php
+$table->integer('order_number')->autoIncrement(); // [tl! remove]
+$table->integer('order_number'); // [tl! add]
+```
+
+```php
+// app/Providers/AppServiceProvider.php
+
+use DuncanMcClean\Cargo\Orders\Eloquent\OrderModel;
+use Illuminate\Database\Eloquent\Model;
+
+Model::creating(function (Model $model) {
+    if ($model instanceof OrderModel) {
+        $model->orderNumber = 5000;
+    }
+});
+```
+:::
+
+
+when you're using a db, the order number column is auto incrementing. if you want to customize order numbers, you'll need to edit the migration 
+
 ## Storage
 Out of the box, orders are stored as YAML files in the `content/cargo/orders` directory. If you wish, you can change the directory in the `cargo.php` config file:
 

src/Stache/Repositories/OrderRepository.php

@@ -14,9 +14,12 @@
 use Illuminate\Support\Facades\Cache;
 use Statamic\Fields\Blueprint as StatamicBlueprint;
 use Statamic\Stache\Stache;
+use Statamic\Support\Traits\Hookable;
 
 class OrderRepository implements RepositoryContract
 {
+    use Hookable;
+
     protected $stache;
     protected $store;
 
@@ -95,7 +98,7 @@ public function save(Order $order): void
         }
 
         if (! $order->orderNumber()) {
-            $order->orderNumber($this->generateOrderNumber());
+            $order->orderNumber($this->generateOrderNumber($order));
         }
 
         $this->store->save($order);
@@ -106,16 +109,19 @@ public function delete(Order $order): void
         $this->store->delete($order);
     }
 
-    private function generateOrderNumber(): int
+    private function generateOrderNumber(Order $order): int
     {
-        return Cache::lock('cargo-order-number', 5)->get(function () {
-            $lastOrder = $this->query()->orderByDesc('order_number')->first();
+        return Cache::lock('cargo-order-number', 5)->get(function () use ($order) {
+            $orderNumber = config('statamic.cargo.minimum_order_number', 1000);
 
-            if (! $lastOrder) {
-                return config('statamic.cargo.minimum_order_number', 1000);
+            if ($lastOrder = $this->query()->orderByDesc('order_number')->first()) {
+                $orderNumber = (int) $lastOrder->orderNumber() + 1;
             }
 
-            return (int) $lastOrder->orderNumber() + 1;
+            return $this->runHooks('generating-order-number', (object) [
+                'order' => $order,
+                'orderNumber' => $orderNumber,
+            ])->orderNumber;
         });
     }
 

tests/Stache/Repositories/OrderRepositoryTest.php

@@ -160,6 +160,22 @@ public function can_generate_order_number()
         $this->assertEquals(1003, $order->orderNumber());
     }
 
+    #[Test]
+    public function can_hook_into_generating_order_number()
+    {
+        $this->repo->hook('generating-order-number', function ($payload, $next) {
+            $payload->orderNumber = 5000;
+
+            return $next($payload);
+        });
+
+        $order = Order::make();
+
+        $this->repo->save($order);
+
+        $this->assertEquals(5000, $order->orderNumber());
+    }
+
     #[Test]
     public function can_delete_an_order()
     {