From 3ca77a98da49783d44d7bda0a956cc300d595050 Mon Sep 17 00:00:00 2001
From: 3m1n3nc3 <mygames.ng@gmail.com>
Date: Sat, 13 Jan 2024 02:39:02 +0100
Subject: [PATCH 1/7] Improve type annotations and PHPDoc

---
 src/Facades/LaravelPayPocket.php    |  5 +++
 src/Interfaces/WalletOperations.php | 45 +++++++++++++++++++++++---
 src/Services/PocketServices.php     | 49 ++++++++++++++++++++++++++---
 src/Traits/BalanceOperation.php     | 36 ++++++++++++++++-----
 src/Traits/HandlesDeposit.php       | 18 +++++++++--
 src/Traits/HandlesPayment.php       |  3 ++
 src/Traits/HasWallet.php            | 19 ++++++++---
 tests/Models/User.php               |  3 +-
 8 files changed, 153 insertions(+), 25 deletions(-)

diff --git a/src/Facades/LaravelPayPocket.php b/src/Facades/LaravelPayPocket.php
index 1c33b5f..48e55f6 100644
--- a/src/Facades/LaravelPayPocket.php
+++ b/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
 {
diff --git a/src/Interfaces/WalletOperations.php b/src/Interfaces/WalletOperations.php
index 47e132d..06163b2 100644
--- a/src/Interfaces/WalletOperations.php
+++ b/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;
 }
diff --git a/src/Services/PocketServices.php b/src/Services/PocketServices.php
index 91db495..a1d6e08 100644
--- a/src/Services/PocketServices.php
+++ b/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);
     }
diff --git a/src/Traits/BalanceOperation.php b/src/Traits/BalanceOperation.php
index abbd4a5..95f8041 100644
--- a/src/Traits/BalanceOperation.php
+++ b/src/Traits/BalanceOperation.php
@@ -9,7 +9,9 @@ trait BalanceOperation
     protected $createdLog;
 
     /**
-     *  Check if Balance is more than zero.
+     * Check if Balance is more than zero.
+     *
+     * @return bool
      */
     public function hasBalance(): bool
     {
@@ -17,27 +19,43 @@ public function hasBalance(): bool
     }
 
     /**
-     *  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] ?? [])
diff --git a/src/Traits/HandlesDeposit.php b/src/Traits/HandlesDeposit.php
index 03cbaf8..ba5f683 100644
--- a/src/Traits/HandlesDeposit.php
+++ b/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.');
diff --git a/src/Traits/HandlesPayment.php b/src/Traits/HandlesPayment.php
index 4bfa835..2f5d608 100644
--- a/src/Traits/HandlesPayment.php
+++ b/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
diff --git a/src/Traits/HasWallet.php b/src/Traits/HasWallet.php
index d30ca89..8f945e8 100644
--- a/src/Traits/HasWallet.php
+++ b/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}'.");
diff --git a/tests/Models/User.php b/tests/Models/User.php
index 7a10991..c9a560a 100644
--- a/tests/Models/User.php
+++ b/tests/Models/User.php
@@ -11,7 +11,8 @@
 
 class User extends Authenticatable implements WalletOperations
 {
-    use HasFactory, Notifiable;
+    use HasFactory;
+    use Notifiable;
     use ManagesWallet;
 
     /**

From ec32b9764af852ea4cddaeb7dd84c9faf13f47b9 Mon Sep 17 00:00:00 2001
From: 3m1n3nc3 <mygames.ng@gmail.com>
Date: Sat, 13 Jan 2024 02:45:29 +0100
Subject: [PATCH 2/7] Fix missing exception

---
 src/Interfaces/WalletOperations.php | 2 +-
 src/Services/PocketServices.php     | 4 ++--
 src/Traits/HandlesPayment.php       | 4 ++--
 3 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/Interfaces/WalletOperations.php b/src/Interfaces/WalletOperations.php
index 06163b2..c41dfce 100644
--- a/src/Interfaces/WalletOperations.php
+++ b/src/Interfaces/WalletOperations.php
@@ -36,7 +36,7 @@ public function hasSufficientBalance(int|float $value): bool;
      * @param int|float $orderValue
      * @param ?string $notes
      *
-     * @throws InsufficientBalanceException
+     * @throws \HPWebdeveloper\LaravelPayPocket\Exceptions\InsufficientBalanceException
      */
     public function pay(int|float $orderValue, ?string $notes = null): void;
 
diff --git a/src/Services/PocketServices.php b/src/Services/PocketServices.php
index a1d6e08..e5c836d 100644
--- a/src/Services/PocketServices.php
+++ b/src/Services/PocketServices.php
@@ -29,7 +29,7 @@ public function deposit(Model $user, string $type, int|float $amount, ?string $n
      * @param ?string $notes
      *
      * @return void
-     * @throws InsufficientBalanceException
+     * @throws \HPWebdeveloper\LaravelPayPocket\Exceptions\InsufficientBalanceException
      */
     public function pay(Model $user, int|float $orderValue, ?string $notes = null): void
     {
@@ -62,4 +62,4 @@ public function walletBalanceByType(Model $user, string $type): float|int
     {
         return $user->getWalletBalanceByType($type);
     }
-}
+}
\ No newline at end of file
diff --git a/src/Traits/HandlesPayment.php b/src/Traits/HandlesPayment.php
index 2f5d608..2266cb8 100644
--- a/src/Traits/HandlesPayment.php
+++ b/src/Traits/HandlesPayment.php
@@ -14,7 +14,7 @@ trait HandlesPayment
      * @param ?string $notes
      *
      * @return void
-     * @throws InsufficientBalanceException
+     * @throws \HPWebdeveloper\LaravelPayPocket\Exceptions\InsufficientBalanceException
      */
     public function pay(int|float $orderValue, ?string $notes = null): void
     {
@@ -46,4 +46,4 @@ public function pay(int|float $orderValue, ?string $notes = null): void
             }
         });
     }
-}
+}
\ No newline at end of file

From 44de2d56e1476d77d2e0ac1ee4a85c955086debb Mon Sep 17 00:00:00 2001
From: 3m1n3nc3 <mygames.ng@gmail.com>
Date: Sat, 13 Jan 2024 02:58:38 +0100
Subject: [PATCH 3/7] Type $walletsInOrder in HandlesPayment's pay() method

---
 src/Traits/HandlesPayment.php | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/src/Traits/HandlesPayment.php b/src/Traits/HandlesPayment.php
index 2266cb8..868e590 100644
--- a/src/Traits/HandlesPayment.php
+++ b/src/Traits/HandlesPayment.php
@@ -25,6 +25,10 @@ public function pay(int|float $orderValue, ?string $notes = null): void
         DB::transaction(function () use ($orderValue, $notes) {
             $remainingOrderValue = $orderValue;
 
+            /**
+             * @var \Illuminate\Support\Collection<TKey, \HPWebdeveloper\LaravelPayPocket\Models
+             * |\HPWebdeveloper\LaravelPayPocket\Traits\BalanceOperation>  $walletsInOrder
+             */
             $walletsInOrder = $this->wallets()->whereIn('type', $this->walletsInOrder())->get();
 
             foreach ($walletsInOrder as $wallet) {
@@ -46,4 +50,4 @@ public function pay(int|float $orderValue, ?string $notes = null): void
             }
         });
     }
-}
\ No newline at end of file
+}

From 6d2ce0ef4dd597380acd9c2482c18cf4c41f454b Mon Sep 17 00:00:00 2001
From: 3m1n3nc3 <mygames.ng@gmail.com>
Date: Sat, 13 Jan 2024 03:11:30 +0100
Subject: [PATCH 4/7] Fix $walletsInOrder type, see last commit.

---
 src/Traits/HandlesPayment.php | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/Traits/HandlesPayment.php b/src/Traits/HandlesPayment.php
index 868e590..d8d83ca 100644
--- a/src/Traits/HandlesPayment.php
+++ b/src/Traits/HandlesPayment.php
@@ -26,8 +26,7 @@ public function pay(int|float $orderValue, ?string $notes = null): void
             $remainingOrderValue = $orderValue;
 
             /**
-             * @var \Illuminate\Support\Collection<TKey, \HPWebdeveloper\LaravelPayPocket\Models
-             * |\HPWebdeveloper\LaravelPayPocket\Traits\BalanceOperation>  $walletsInOrder
+             * @var \Illuminate\Support\Collection<TKey, \HPWebdeveloper\LaravelPayPocket\Models\Wallet>
              */
             $walletsInOrder = $this->wallets()->whereIn('type', $this->walletsInOrder())->get();
 

From eef8c488bb2bc5f950e17d570aed94a4acdf3bd6 Mon Sep 17 00:00:00 2001
From: 3m1n3nc3 <mygames.ng@gmail.com>
Date: Sat, 13 Jan 2024 04:24:24 +0100
Subject: [PATCH 5/7] Fix readme link to transaction-info-8i8

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 335bc91..b5ccdfa 100644
--- a/README.md
+++ b/README.md
@@ -57,7 +57,7 @@ This command will automatically publish the `WalletEnums.php` file into your app
 
 ## Updating
 
-If updating from version `<= 1.0.3`, new migration and config files have been added to support the new [Transaction Info Feature](#transaction-info)
+If updating from version `<= 1.0.3`, new migration and config files have been added to support the new [Transaction Info Feature](#transaction-info-8i8)
 
 Follow the [Installation](#installation) Steps 2 and 3 to update your migrations.
 

From 47dec5a902059238526cfe53571b8f8516c2572c Mon Sep 17 00:00:00 2001
From: 3m1n3nc3 <mygames.ng@gmail.com>
Date: Sat, 13 Jan 2024 04:34:48 +0100
Subject: [PATCH 6/7] Update README

---
 README.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index b5ccdfa..3def468 100644
--- a/README.md
+++ b/README.md
@@ -55,9 +55,9 @@ php artisan vendor:publish --tag="config"
 
 This command will automatically publish the `WalletEnums.php` file into your application's `app/Enums` directory.
 
-## Updating
+## Updating to ^2.0.0
 
-If updating from version `<= 1.0.3`, new migration and config files have been added to support the new [Transaction Info Feature](#transaction-info-8i8)
+If updating to version `^2.0.0`, new migration and config files have been added to support the new [Transaction Notes Feature](#transaction-notes-8i8)
 
 Follow the [Installation](#installation) Steps 2 and 3 to update your migrations.
 
@@ -137,7 +137,7 @@ LaravelPayPocket::deposit($user, 'wallet_1', 123.45);
 
 Note: `wallet_1` and `wallet_2` must already be defined in the `WalletEnums`.
 
-#### Transaction Info ([#8][i8])
+#### Transaction Notes ([#8][i8])
 
 In a case where you want to enter descriptions for a particular transaction, the `$notes` param allows you to provide information about why a transaction happened.
 
@@ -236,4 +236,4 @@ Please review [our security policy](../../security/policy) on how to report secu
 
 The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
 
-[i8]: Tag link (will be updated soon)
+[i8]: https://github.com/HPWebdeveloper/laravel-pay-pocket/pull/10

From 4e577d0cecc0600c54f6f69a18e68e37b4c53c53 Mon Sep 17 00:00:00 2001
From: 3m1n3nc3 <mygames.ng@gmail.com>
Date: Sat, 13 Jan 2024 04:35:24 +0100
Subject: [PATCH 7/7] Remove README changes

---
 README.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 3def468..335bc91 100644
--- a/README.md
+++ b/README.md
@@ -55,9 +55,9 @@ php artisan vendor:publish --tag="config"
 
 This command will automatically publish the `WalletEnums.php` file into your application's `app/Enums` directory.
 
-## Updating to ^2.0.0
+## Updating
 
-If updating to version `^2.0.0`, new migration and config files have been added to support the new [Transaction Notes Feature](#transaction-notes-8i8)
+If updating from version `<= 1.0.3`, new migration and config files have been added to support the new [Transaction Info Feature](#transaction-info)
 
 Follow the [Installation](#installation) Steps 2 and 3 to update your migrations.
 
@@ -137,7 +137,7 @@ LaravelPayPocket::deposit($user, 'wallet_1', 123.45);
 
 Note: `wallet_1` and `wallet_2` must already be defined in the `WalletEnums`.
 
-#### Transaction Notes ([#8][i8])
+#### Transaction Info ([#8][i8])
 
 In a case where you want to enter descriptions for a particular transaction, the `$notes` param allows you to provide information about why a transaction happened.
 
@@ -236,4 +236,4 @@ Please review [our security policy](../../security/policy) on how to report secu
 
 The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
 
-[i8]: https://github.com/HPWebdeveloper/laravel-pay-pocket/pull/10
+[i8]: Tag link (will be updated soon)