Improve type annotations and PHPDoc

Author: 3m1n3nc3

src/Facades/LaravelPayPocket.php

@@ -6,6 +6,11 @@
 
 /**
  * @see \HPWebdeveloper\LaravelPayPocket\Services\PocketServices
+ *
+ * @method static void pay(\Illuminate\Database\Eloquent\Model $user, int|float $orderValue, ?string $notes = null)
+ * @method static bool deposit(\Illuminate\Database\Eloquent\Model $user, string $type, int|float $amount, ?string $notes = null)
+ * @method static int|float checkBalance(\Illuminate\Database\Eloquent\Model $user)
+ * @method static int|float walletBalanceByType(\Illuminate\Database\Eloquent\Model $user, string $type)
  */
 class LaravelPayPocket extends Facade
 {

src/Interfaces/WalletOperations.php

@@ -4,13 +4,50 @@
 
 interface WalletOperations
 {
-    public function getWalletBalanceAttribute();
+    /**
+     * Get User's Wallet Balance
+     *
+     * @return int|float
+     */
+    public function getWalletBalanceAttribute(): int|float;
 
-    public function getWalletBalanceByType(string $walletType);
+    /**
+     * Get the balance of a specific wallet type.
+     *
+     *
+     * @param string $walletType
+     *
+     * @return float|int
+     */
+    public function getWalletBalanceByType(string $walletType): float|int;
 
-    public function hasSufficientBalance($value): bool;
+    /**
+     *  Check if User's wallet balance is more than given value
+     *
+     * @param int|float $value
+     *
+     * @return bool
+     */
+    public function hasSufficientBalance(int|float $value): bool;
 
-    public function pay(int|float $orderValue, ?string $notes = null);
+    /**
+     * Pay the order value from the user's wallets.
+     *
+     * @param int|float $orderValue
+     * @param ?string $notes
+     *
+     * @throws InsufficientBalanceException
+     */
+    public function pay(int|float $orderValue, ?string $notes = null): void;
 
+    /**
+     * Deposit an amount to the user's wallet of a specific type.
+     *
+     * @param string $type
+     * @param int|float $amount
+     * @param ?string $notes
+     *
+     * @return bool
+     */
     public function deposit(string $type, int|float $amount, ?string $notes = null): bool;
 }

src/Services/PocketServices.php

@@ -2,24 +2,63 @@
 
 namespace HPWebdeveloper\LaravelPayPocket\Services;
 
+use Illuminate\Database\Eloquent\Model;
+
 class PocketServices
 {
-    public function deposit($user, $type, $amount, $notes = null)
+    /**
+     * Deposit an amount to the user's wallet of a specific type.
+     *
+     * @param \Illuminate\Database\Eloquent\Model $user
+     * @param string $type
+     * @param int|float $amount
+     * @param ?string $notes
+     *
+     * @return bool
+     */
+    public function deposit(Model $user, string $type, int|float $amount, ?string $notes = null): bool
     {
         return $user->deposit($type, $amount, $notes);
     }
 
-    public function pay($user, $orderValue, $notes = null)
+    /**
+     * Pay the order value from the user's wallets.
+     *
+     * @param \Illuminate\Database\Eloquent\Model $user
+     * @param int|float $orderValue
+     * @param ?string $notes
+     *
+     * @return void
+     * @throws InsufficientBalanceException
+     */
+    public function pay(Model $user, int|float $orderValue, ?string $notes = null): void
     {
-        return $user->pay($orderValue, $notes);
+        $user->pay($orderValue, $notes);
     }
 
-    public function checkBalance($user)
+    /**
+     * Get the balance of the user.
+     *
+     *
+     * @param \Illuminate\Database\Eloquent\Model $user
+     *
+     * @return float|int
+     */
+    public function checkBalance(Model $user): int|float
     {
         return $user->walletBalance;
     }
 
-    public function walletBalanceByType($user, $type)
+    /**
+     * Get the balance of a specific wallet type.
+     *
+     *
+     * @param \Illuminate\Database\Eloquent\Model $user
+     * @param string $type
+     *
+     * @return float|int
+     */
+    public function walletBalanceByType(Model $user, string $type): float|int
     {
         return $user->getWalletBalanceByType($type);
     }

src/Traits/BalanceOperation.php

@@ -9,35 +9,53 @@ trait BalanceOperation
     protected $createdLog;
 
     /**
-     *  Check if Balance is more than zero.
+     * Check if Balance is more than zero.
+     *
+     * @return bool
      */
     public function hasBalance(): bool
     {
         return $this->balance > 0;
     }
 
     /**
-     *  Decrement Balance and create a log entry.
+     * Decrement Balance and create a log entry.
+     *
+     * @param int|float $value
+     * @param ?string $notes
+     *
+     * @return void
      */
-    public function decrementAndCreateLog($value, $notes = null): void
+    public function decrementAndCreateLog(int|float $value, ?string $notes = null): void
     {
         $this->createLog('dec', $value, $notes);
         $this->decrement('balance', $value);
     }
 
     /**
-     *  Increment Balance and create a log entry.
+     * Increment Balance and create a log entry.
+     *
+     * @param int|float $value
+     * @param ?string $notes
+     *
+     * @return void
      */
-    public function incrementAndCreateLog($value, $notes = null): void
+    public function incrementAndCreateLog(int|float $value, ?string $notes = null): void
     {
         $this->createLog('inc', $value, $notes);
         $this->increment('balance', $value);
     }
 
     /**
-     *  Create a new log record
+     * Create a new log record
+     *
+     * @param string $logType
+     * @param int|float $value
+     * @param ?string $notes
+     *
+     * @return void
      */
-    protected function createLog($logType, $value, $notes = null): void
+    protected function createLog(string $logType, int|float $value, ?string $notes = null): void
     {
         $currentBalance = $this->balance ?? 0;
 
@@ -46,6 +64,10 @@ protected function createLog($logType, $value, $notes = null): void
         $refGen = config('pay-pocket.log_reference_generator', [
             Str::class, 'random', [config('pay-pocket.log_reference_length', 12)],
         ]);
+        $refGen = [
+            Str::class, 'random', [config('pay-pocket.log_reference_length', 12)],
+        ];
+
         $reference = config('pay-pocket.reference_string_prefix', '');
         $reference .= isset($refGen[0], $refGen[1])
             ? $refGen[0]::{$refGen[1]}(...$refGen[2] ?? [])

src/Traits/HandlesDeposit.php

@@ -14,6 +14,13 @@ trait HandlesDeposit
 {
     /**
      * Deposit an amount to the user's wallet of a specific type.
+     *
+     * @param string $type
+     * @param int|float $amount
+     * @param ?string $notes
+     *
+     * @return bool
+     * @throws InvalidDepositException|InvalidValueException|InvalidWalletTypeException
      */
     public function deposit(string $type, int|float $amount, ?string $notes = null): bool
     {
@@ -38,6 +45,8 @@ public function deposit(string $type, int|float $amount, ?string $notes = null):
 
     /**
      * Get depositable types from WalletEnums.
+     *
+     * @return array
      */
     private function getDepositableTypes(): array
     {
@@ -50,12 +59,15 @@ private function getDepositableTypes(): array
     }
 
     /**
-     * Check if the given tyep is valid.
+     * Check if the given type is valid.
+     *
+     * @var string $type
+     * @var array $depositable
      *
-     * @param  string  $type
      * @return bool
+     * @throws InvalidWalletTypeException
      */
-    private function isRequestValid($type, array $depositable)
+    private function isRequestValid($type, array $depositable): bool
     {
         if (! array_key_exists($type, $depositable)) {
             throw new InvalidWalletTypeException('Invalid deposit type.');

src/Traits/HandlesPayment.php

@@ -10,7 +10,10 @@ trait HandlesPayment
     /**
      * Pay the order value from the user's wallets.
      *
+     * @param int|float $orderValue
+     * @param ?string $notes
      *
+     * @return void
      * @throws InsufficientBalanceException
      */
     public function pay(int|float $orderValue, ?string $notes = null): void

src/Traits/HasWallet.php

@@ -22,9 +22,11 @@ public function wallets()
     }
 
     /**
-     *  Get User's Wallet Balance
+     * Get User's Wallet Balance
+     *
+     * @return int|float
      */
-    public function getWalletBalanceAttribute()
+    public function getWalletBalanceAttribute(): int|float
     {
 
         $totalBalance = 0;
@@ -39,23 +41,30 @@ public function getWalletBalanceAttribute()
         }
 
         return $totalBalance;
-
     }
 
     /**
      *  Check if User's wallet balance is more than given value
+     *
+     * @param int|float $value
+     *
+     * @return bool
      */
-    public function hasSufficientBalance($value): bool
+    public function hasSufficientBalance(int|float $value): bool
     {
         return (int) $this->walletBalance >= (int) $value;
     }
 
+
     /**
      * Get the balance of a specific wallet type.
      *
+     *
+     * @param string $walletType
+     *
      * @return float|int
      */
-    public function getWalletBalanceByType(string $walletType)
+    public function getWalletBalanceByType(string $walletType): float|int
     {
         if (! WalletEnums::isValid($walletType)) {
             throw new InvalidWalletTypeException("Invalid wallet type '{$walletType}'.");

tests/Models/User.php

@@ -11,7 +11,8 @@
 
 class User extends Authenticatable implements WalletOperations
 {
-    use HasFactory, Notifiable;
+    use HasFactory;
+    use Notifiable;
     use ManagesWallet;
 
     /**