ronmrcdo / laravel-inventory

src/Traits/HasItemStocks.php

<?php

namespace Ronmrcdo\Inventory\Traits;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Support\Facades\DB;
use Ronmrcdo\Inventory\Exceptions\NotEnoughStockException;
use Ronmrcdo\Inventory\Exceptions\InvalidMovementException;

trait HasItemStocks
{
	/**
     * Stores the quantity before an update.
     *
     * @var int|float|string
     */
    private $beforeQuantity = 0;

    /**
     * Stores the reason for updating / creating a stock.
     *
     * @var string
     */
    public $reason = '';

    /**
     * Stores the cost for updating a stock.
     *
     * @var int|float|string
     */
	public $cost = 0;
	
	protected static function bootHasItemStocks()
	{
		static::creating(function (Model $model) {

            /*
             * Check if a reason has been set, if not
             * let's retrieve the default first entry reason
             */
            if (!$model->reason) {
                $model->reason = 'First Item Record; Stock Increase';
            }
		});
		
		static::created(function (Model $model) {
            $model->postCreate();
		});
		
		static::updating(function (Model $model) {
            /*
             * Retrieve the original quantity before it was updated,
             * so we can create generate an update with it
             */
            $model->beforeQuantity = $model->getOriginal('quantity');

            /*
             * Check if a reason has been set, if not let's retrieve the default change reason
             */
            if (!$model->reason) {
                $model->reason = 'Stock Adjustment';
            }
		});
		
		static::updated(function (Model $model) {
            $model->postUpdate();
        });
	}

	/**
     * Generates a stock movement on the creation of a stock.
     */
    public function postCreate()
    {
        if (!$this->getLastMovement()) {
            $this->generateStockMovement(0, $this->quantity, $this->reason, $this->cost);
        }
	}
	
	/**
     * Generates a stock movement after a stock is updated.
     */
    public function postUpdate()
    {
        $this->generateStockMovement($this->beforeQuantity, $this->quantity, $this->reason, $this->cost);
	}
	
	/**
     * Performs a quantity update. Automatically determining
     * depending on the quantity entered if stock is being taken
     * or added.
     *
     * @param int|float|string $quantity
     * @param string           $reason
     * @param int|float|string $cost
     *
     * @throws InvalidQuantityException
     *
     * @return $this
     */
    public function updateQuantity($quantity, $reason = '', $cost = 0)
    {
        if ($this->isValidQuantity($quantity)) {

It seems like isValidQuantity() must be provided by classes using this trait. How about adding it as abstract method to this trait?

            return $this->processUpdateQuantityOperation($quantity, $reason, $cost);

The expression return $this->processUpdateQuantityOperation($quantity, $reason, $cost) could also return false which is incompatible with the documented return type Ronmrcdo\Inventory\Traits\HasItemStocks. Did you maybe forget to handle an error condition?

        }
    }

    /**
     * Removes the specified quantity from the current stock.
     *
     * @param int|float|string $quantity
     * @param string           $reason
     * @param int|float|string $cost
     *
     * @return $this|bool
     */
    public function remove($quantity, $reason = '', $cost = 0)
    {
        return $this->take($quantity, $reason, $cost);
    }

    /**
     * Processes a 'take' operation on the current stock.
     *
     * @param int|float|string $quantity
     * @param string           $reason
     * @param int|float|string $cost
     *
     * @throws InvalidQuantityException
     * @throws NotEnoughStockException
     *
     * @return $this|bool
     */
    public function take($quantity, $reason = '', $cost = 0)
    {
        if ($this->isValidQuantity($quantity) && $this->hasEnoughStock($quantity)) {
            return $this->processTakeOperation($quantity, $reason, $cost);
        }
    }

    /**
     * Alias for put function.
     *
     * @param int|float|string $quantity
     * @param string           $reason
     * @param int|float|string $cost
     *
     * @return $this
     */
    public function add($quantity, $reason = '', $cost = 0)
    {
        return $this->put($quantity, $reason, $cost);

The expression return $this->put($quantity, $reason, $cost) could also return false which is incompatible with the documented return type Ronmrcdo\Inventory\Traits\HasItemStocks. Did you maybe forget to handle an error condition?

    }

    /**
     * Processes a 'put' operation on the current stock.
     *
     * @param int|float|string $quantity
     * @param string           $reason
     * @param int|float|string $cost
     *
     * @throws InvalidQuantityException
     *
     * @return $this
     */
    public function put($quantity, $reason = '', $cost = 0)
    {
        if ($this->isValidQuantity($quantity)) {
            return $this->processPutOperation($quantity, $reason, $cost);

The expression return $this->processPutOperation($quantity, $reason, $cost) could also return false which is incompatible with the documented return type Ronmrcdo\Inventory\Traits\HasItemStocks. Did you maybe forget to handle an error condition?

        }
    }

    /**
     * Moves a stock to the specified location.
     *
     * @param $location
     *
     * @return bool
     */
    public function moveTo($location)
    {
        $location = $this->getLocation($location);

It seems like getLocation() must be provided by classes using this trait. How about adding it as abstract method to this trait?

        return $this->processMoveOperation($location);
    }

    /**
     * Rolls back the last movement, or the movement specified. If recursive is set to true,
     * it will rollback all movements leading up to the movement specified.
     *
     * @param mixed $movement
     * @param bool  $recursive
     *
     * @return $this|bool
     */
    public function rollback($movement = null, $recursive = false)
    {
        if ($movement) {
            return $this->rollbackMovement($movement, $recursive);
        } else {
            $movement = $this->getLastMovement();

            if ($movement) {
                return $this->processRollbackOperation($movement, $recursive);
            }
        }

        return false;
    }

    /**
     * Rolls back a specific movement.
     *
     * @param mixed $movement
     * @param bool  $recursive
     *
     * @throws InvalidMovementException
     *
     * @return $this|bool
     */
    public function rollbackMovement($movement, $recursive = false)
    {
        $movement = $this->getMovement($movement);

        return $this->processRollbackOperation($movement, $recursive);
    }

    /**
     * Returns true if there is enough stock for the specified quantity being taken.
     * Throws NotEnoughStockException otherwise.
     *
     * @param int|float|string $quantity
     *
     * @throws NotEnoughStockException
     *
     * @return bool
     */
    public function hasEnoughStock($quantity = 0)
    {
        /*
         * Using double equals for validation of complete value only, not variable type. For example:
         * '20' (string) equals 20 (int)
         */
        if ($this->quantity == $quantity || $this->quantity > $quantity) {
            return true;
        }

        $message = 'Not enough stock. Tried to take '. $quantity.' but only '. $this->quantity .' is available';

        throw new NotEnoughStockException($message);
    }

    /**
     * Returns the last movement on the current stock record.
     *
     * @return mixed
     */
    public function getLastMovement()
    {
        $movement = $this->movements()->orderBy('created_at', 'DESC')->first();

It seems like movements() must be provided by classes using this trait. How about adding it as abstract method to this trait?

        if ($movement) {
            return $movement;
        }

        return false;
    }

    /**
     * Returns a movement depending on the specified argument. If an object is supplied, it is checked if it
     * is an instance of an eloquent model. If a numeric value is entered, it is retrieved by it's ID.
     *
     * @param mixed $movement
     *
     * @throws InvalidMovementException
     *
     * @return mixed
     */
    public function getMovement($movement)
    {
        if ($this->isModel($movement)) {

It seems like isModel() must be provided by classes using this trait. How about adding it as abstract method to this trait?

            return $movement;
        } elseif (is_numeric($movement)) {
            return $this->getMovementById($movement);
        } else {
            $message = 'Movement '. $movement .' is invalid';

            throw new InvalidMovementException($message);
        }
    }

    /**
     * Creates and returns a new un-saved stock transaction
     * instance with the current stock ID attached.
     *
     * @param string $name
     *
     * @return \Illuminate\Database\Eloquent\Model
     */
    public function newTransaction($name = '')
    {
        $transaction = $this->transactions()->getRelated();

It seems like transactions() must be provided by classes using this trait. How about adding it as abstract method to this trait?

        /*
         * Set the transaction attributes so they don't
         * need to be set manually
         */
        $transaction->stock_id = $this->getKey();

It seems like getKey() must be provided by classes using this trait. How about adding it as abstract method to this trait?

        $transaction->name = $name;

        return $transaction;
    }

    /**
     * Retrieves a movement by the specified ID.
     *
     * @param int|string $id
     *
     * @return mixed
     */
    private function getMovementById($id)
    {
        return $this->movements()->find($id);
    }

    /**
     * Processes a quantity update operation.
     *
     * @param int|float|string $quantity
     * @param string           $reason
     * @param int|float|string $cost
     *
     * @return $this
     */
    private function processUpdateQuantityOperation($quantity, $reason = '', $cost = 0)
    {
        if ($quantity > $this->quantity) {
            $putting = $quantity - $this->quantity;

            return $this->put($putting, $reason, $cost);

The expression return $this->put($putting, $reason, $cost) could also return false which is incompatible with the documented return type Ronmrcdo\Inventory\Traits\HasItemStocks. Did you maybe forget to handle an error condition?

        } else {
            $taking = $this->quantity - $quantity;

            return $this->take($taking, $reason, $cost);
        }
    }

    /**
     * Processes removing quantity from the current stock.
     *
     * @param int|float|string $taking
     * @param string           $reason
     * @param int|float|string $cost
     *
     * @return $this|bool
     */
    private function processTakeOperation($taking, $reason = '', $cost = 0)
    {
        $left = $this->quantity - $taking;

        /*
         * If the updated total and the beginning total are the same, we'll check if
         * duplicate movements are allowed. We'll return the current record if
         * they aren't.
         */
        if ($left == $this->quantity && !$this->allowDuplicateMovementsEnabled()) {
            return $this;
        }

        $this->quantity = $left;

The property quantity does not exist. Although not strictly required by PHP, it is generally a best practice to declare properties explicitly.

        $this->setReason($reason);

        $this->setCost($cost);

        DB::beginTransaction();

        try {
            if ($this->save()) {

It seems like save() must be provided by classes using this trait. How about adding it as abstract method to this trait?

                $this->fireModelEvent('inventory.stock.taken', [

It seems like fireModelEvent() must be provided by classes using this trait. How about adding it as abstract method to this trait?

                    'stock' => $this,
                ]);

                return $this;
            }
        } catch (\Exception $e) {
            DB::rollBack();
        }

        return false;
    }

    /**
     * Processes adding quantity to current stock.
     *
     * @param int|float|string $putting
     * @param string           $reason
     * @param int|float|string $cost
     *
     * @return $this|bool
     */
    private function processPutOperation($putting, $reason = '', $cost = 0)
    {
        $before = $this->quantity;

        $total = $putting + $before;

        /*
         * If the updated total and the beginning total are the same,
         * we'll check if duplicate movements are allowed
         */
        if ($total == $this->quantity && !$this->allowDuplicateMovementsEnabled()) {
            return $this;
        }

        $this->quantity = $total;

The property quantity does not exist. Although not strictly required by PHP, it is generally a best practice to declare properties explicitly.

        $this->setReason($reason);

        $this->setCost($cost);

        DB::beginTransaction();

        try {
            if ($this->save()) {
                DB::commit();

                $this->fireModelEvent('inventory.stock.added', [
                    'stock' => $this,
                ]);

                return $this;
            }
        } catch (\Exception $e) {
            DB::rollBack();
        }

        return false;
    }

    /**
     * Processes the stock moving from it's current
     * location, to the specified location.
     *
     * @param mixed $location
     *
     * @return bool
     */
    private function processMoveOperation(Model $location)
    {
        $this->location_id = $location->getKey();

The property location_id does not exist. Although not strictly required by PHP, it is generally a best practice to declare properties explicitly.

        DB::beginTransaction();

        try {
            if ($this->save()) {
                

                $this->fireModelEvent('inventory.stock.moved', [
                    'stock' => $this,
                ]);
				
				DB::commit();
                return $this;

The expression return $this returns the type Ronmrcdo\Inventory\Traits\HasItemStocks which is incompatible with the documented return type boolean.

            }
        } catch (\Exception $e) {
            DB::rollBack();
        }

        return false;
    }

    /**
     * Processes a single rollback operation.
     *
     * @param mixed $movement
     * @param bool  $recursive
     *
     * @return $this|bool
     */
    private function processRollbackOperation(Model $movement, $recursive = false)
    {
        if ($recursive) {
            return $this->processRecursiveRollbackOperation($movement);

The expression return $this->processRecursiveRollbackOperation($movement) returns the type array which is incompatible with the documented return type Ronmrcdo\Inventory\Traits\HasItemStocks|boolean.

        }

        $this->quantity = $movement->before;

The property quantity does not exist. Although not strictly required by PHP, it is generally a best practice to declare properties explicitly.

        $reason = 'Rolled back to movement ID: '. $movement->getOriginal('id') .' on '. $movement->getOriginal('created_at');

Are you sure $movement->getOriginal('created_at') of type array|mixed can be used in concatenation?

Are you sure $movement->getOriginal('id') of type array|mixed can be used in concatenation?

        $this->setReason($reason);

        if ($this->rollbackCostEnabled()) {
            $this->setCost($movement->cost);

It seems like $movement->cost can also be of type Illuminate\Database\Eloquent\Builder&Illuminate\Database\Eloquent\Relations\Relation and Illuminate\Database\Eloquent\Relations\Relation; however, parameter $cost of Ronmrcdo\Inventory\Traits\HasItemStocks::setCost() does only seem to accept double|integer|string, maybe add an additional type check?

            $this->reverseCost();
        }

        DB::beginTransaction();

        try {
            if ($this->save()) {
                DB::commit();

                $this->fireModelEvent('inventory.stock.rollback', [
                    'stock' => $this,
                ]);

                return $this;
            }
        } catch (\Exception $e) {
            DB::rollBack();
        }

        return false;
    }

    /**
     * Processes a recursive rollback operation.
     *
     * @param mixed $movement
     *
     * @return array
     */
    private function processRecursiveRollbackOperation(Model $movement)
    {
        /*
         * Retrieve movements that were created after
         * the specified movement, and order them descending
         */
        $movements = $this
            ->movements()
            ->where('created_at', '>=', $movement->getOriginal('created_at'))
            ->orderBy('created_at', 'DESC')
            ->get();

        $rollbacks = [];

        if ($movements->count() > 0) {
            foreach ($movements as $movement) {
                $rollbacks = $this->processRollbackOperation($movement);
            }
        }

        return $rollbacks;

The expression return $rollbacks also could return the type Ronmrcdo\Inventory\Traits\HasItemStocks|false which is incompatible with the documented return type array.

    }

    /**
     * Creates a new stock movement record.
     *
     * @param int|float|string $before
     * @param int|float|string $after
     * @param string           $reason
     * @param int|float|string $cost
     *
     * @return \Illuminate\Database\Eloquent\Model
     */
    private function generateStockMovement($before, $after, $reason = '', $cost = 0)
    {
        $insert = [
            'stock_id' => $this->getKey(),
            'before' => $before,
            'after' => $after,
            'reason' => $reason,
            'cost' => $cost,
        ];

        return $this->movements()->create($insert);
    }

    /**
     * Sets the cost attribute.
     *
     * @param int|float|string $cost
     */
    private function setCost($cost = 0)
    {
        $this->cost = $cost;
    }

    /**
     * Reverses the cost of a movement.
     */
    private function reverseCost()
    {
        if ($this->isPositive($this->cost)) {

It seems like isPositive() must be provided by classes using this trait. How about adding it as abstract method to this trait?

            $this->setCost(-abs($this->cost));
        } else {
            $this->setCost(abs($this->cost));
        }
    }

    /**
     * Sets the reason attribute.
     *
     * @param string $reason
     */
    private function setReason($reason = '')
    {
        $this->reason = $reason;
    }

    /**
     * Returns true/false from the configuration file determining
     * whether or not stock movements can have the same before and after
     * quantities.
     *
     * @return bool
     */
    private function allowDuplicateMovementsEnabled()
    {
        return false;
    }

    /**
     * Returns true/false from the configuration file determining
     * whether or not to rollback costs when a rollback occurs on
     * a stock.
     *
     * @return bool
     */
    private function rollbackCostEnabled()
    {
        return true;
    }

}