Updated cancel transaction method to accept reason and cost arguments…

…, updated stateable interface with correct arguments, added more documentation

docs/TRANSACTIONS.md

@@ -4,7 +4,8 @@ In update 1.4.*, inventory transactions were implemented. Transactions are a way
 several different uses depending on the situation. Every transaction automatically creates a history trail with user accountability, 
 so you're able to see the complete history of each transaction and who performed what for each state change. On any transaction
 method that <b>modifies the stock in some way</b> accepts a `$reason` and `$cost` argument. These reasons and costs will be used
-when updating the stock record.
+when updating the stock record. These arguments are <b>always</b> optional, and are only included in the methods below
+for demonstration.
 
 ### Creating a transaction
 
@@ -171,7 +172,7 @@ Or if we used all of the stock, we can use the `remove()` method without specify
     $transaction->removeAll();
 
     echo $transaction->state; //Returns 'inventory-removed'
-            
+
     $transaction->isRemoved(); // Returns true
 
 If the quantity in either methods (`release($quantity)` or `remove($quantity)`) exceed the amount of quantity inside the
@@ -187,7 +188,7 @@ Only transactions that are opened, checked out, reserved, back ordered, ordered,
     $transaction->cancel();
 
     // Cancel a checked out transaction, this will return the stock into the inventory
-    $transaction->checkout(5)->cancel();
+    $transaction->checkout(5)->cancel($reason = "User cancelled checkout", $cost = 0);
 
     // Cancel a reserved transaction, this will return the stock into the inventory
     $transaction->reserved(5)->cancel();

src/Stevebauman/Inventory/Interfaces/StateableInterface.php

@@ -35,45 +35,45 @@ interface StateableInterface
     const STATE_CANCELLED = 'cancelled';
     const STATE_OPENED = 'opened';
 
-    public function checkout($quantity = NULL);
+    public function checkout($quantity = NULL, $reason = '', $cost = 0);
 
-    public function sold($quantity = NULL);
+    public function sold($quantity = NULL, $reason = '', $cost = 0);
 
-    public function soldAmount($quantity);
+    public function soldAmount($quantity, $reason = '', $cost = 0);
 
-    public function returned($quantity = NULL);
+    public function returned($quantity = NULL, $reason = '', $cost = 0);
 
-    public function returnedPartial($quantity);
+    public function returnedPartial($quantity, $reason = '', $cost = 0);
 
-    public function returnedAll();
+    public function returnedAll($reason = '', $cost = 0);
 
     public function reserved($quantity = NULL, $backOrder = false);
 
     public function backOrder($quantity);
 
-    public function fillBackOrder();
+    public function fillBackOrder($reason = '', $cost = 0);
 
     public function ordered($quantity);
 
-    public function received($quantity = NULL);
+    public function received($quantity = NULL, $reason = '', $cost = 0);
 
-    public function receivedPartial($quantity);
+    public function receivedPartial($quantity, $reason = '', $cost = 0);
 
-    public function receivedAll();
+    public function receivedAll($reason = '', $cost = 0);
 
-    public function hold($quantity);
+    public function hold($quantity, $reason = '', $cost = 0);
 
-    public function release($quantity = NULL);
+    public function release($quantity = NULL, $reason = '', $cost = 0);
 
-    public function releasePartial($quantity);
+    public function releasePartial($quantity, $reason = '', $cost = 0);
 
-    public function releaseAll();
+    public function releaseAll($reason = '', $cost = 0);
 
-    public function remove($quantity = NULL);
+    public function remove($quantity = NULL, $reason = '', $cost = 0);
 
-    public function removePartial($quantity);
+    public function removePartial($quantity, $reason = '', $cost = 0);
 
     public function removeAll();
 
-    public function cancel();
+    public function cancel($reason = '', $cost = 0);
 }

src/Stevebauman/Inventory/Traits/InventoryTransactionTrait.php

@@ -949,9 +949,12 @@ public function removePartial($quantity, $reason = '', $cost = 0)
      * Transactions with states such as sold, returned, order-received,
      * and inventory released CAN NOT be cancelled.
      *
-     * @return mixed
+     * @param string $reason
+     * @param int $cost
+     * @return $this|bool|InventoryTransactionTrait
+     * @throws InvalidTransactionStateException
      */
-    public function cancel()
+    public function cancel($reason = '', $cost = 0)
     {
         $this->validatePreviousState(array(
             NULL,
@@ -974,11 +977,11 @@ public function cancel()
         switch($beforeState)
         {
             case $this::STATE_COMMERCE_CHECKOUT:
-                return $this->processStockPutAndSave($beforeQuantity, $event);
+                return $this->processStockPutAndSave($beforeQuantity, $event, $reason, $cost);
             case $this::STATE_COMMERCE_RESERVED:
-                return $this->processStockPutAndSave($beforeQuantity, $event);
+                return $this->processStockPutAndSave($beforeQuantity, $event, $reason, $cost);
             case $this::STATE_INVENTORY_ON_HOLD:
-                return $this->processStockPutAndSave($beforeQuantity, $event);
+                return $this->processStockPutAndSave($beforeQuantity, $event, $reason, $cost);
             default:
                 return $this->processSave($event);
         }