Refactor PHPDoc comments and improve type hints across multiple interfaces and models

- Removed redundant PHPDoc comments in the Confirmable and ProductLimitedInterface interfaces.
- Updated PHPDoc comments to include type hints for return values in various DTOs and services.
- Enhanced type safety by specifying generic types in relationships within the Wallet model and related traits.
- Cleaned up unused comments and improved clarity in method signatures across several classes.
- Ensured consistency in type declarations and added assertions where necessary for better code quality.

Author: rez1dent3

phpstan.src.baseline.neon

@@ -18,13 +18,6 @@
 interface Confirmable
 {
     /**
-     * Confirm the transaction.
-     *
-     * This method confirms the given transaction if it is not already confirmed.
-     *
-     * @param Transaction $transaction The transaction to confirm.
-     * @return bool Returns true if the transaction was confirmed, false otherwise.
-     *
      * @throws BalanceIsEmpty          If the balance is empty.
      * @throws InsufficientFunds       If there are insufficient funds.
      * @throws ConfirmedInvalid         If the transaction is already confirmed.
@@ -37,15 +30,6 @@ interface Confirmable
     public function confirm(Transaction $transaction): bool;
 
     /**
-     * Safely confirms the transaction.
-     *
-     * This method attempts to confirm the given transaction. If an exception occurs during the confirmation process,
-     * it will be caught and handled. If the confirmation is successful, true will be returned. If an exception occurs,
-     * false will be returned.
-     *
-     * @param Transaction $transaction The transaction to confirm.
-     * @return bool Returns true if the transaction was confirmed, false otherwise.
-     *
      * @throws BalanceIsEmpty          If the balance is empty.
      * @throws InsufficientFunds       If there are insufficient funds.
      * @throws ConfirmedInvalid         If the transaction is already confirmed.
@@ -58,16 +42,6 @@ public function confirm(Transaction $transaction): bool;
     public function safeConfirm(Transaction $transaction): bool;
 
     /**
-     * Reset the confirmation of the transaction.
-     *
-     * This method is used to remove the confirmation from a transaction.
-     * If the transaction is already confirmed, a `ConfirmedInvalid` exception will be thrown.
-     * If the transaction does not belong to the wallet, a `WalletOwnerInvalid` exception will be thrown.
-     * If the transaction was not found, a `RecordNotFoundException` will be thrown.
-     *
-     * @param Transaction $transaction The transaction to reset.
-     * @return bool Returns true if the confirmation was reset, false otherwise.
-     *
      * @throws UnconfirmedInvalid       If the transaction is not confirmed.
      * @throws WalletOwnerInvalid       If the transaction does not belong to the wallet.
      * @throws RecordNotFoundException  If the transaction was not found.
@@ -77,30 +51,9 @@ public function safeConfirm(Transaction $transaction): bool;
      */
     public function resetConfirm(Transaction $transaction): bool;
 
-    /**
-     * Safely reset the confirmation of the transaction.
-     *
-     * This method is used to remove the confirmation from a transaction.
-     * If the transaction is already confirmed, the confirmation will be reset.
-     * If the transaction does not belong to the wallet, a `WalletOwnerInvalid` exception will be thrown.
-     * If the transaction was not found, a `RecordNotFoundException` will be thrown.
-     *
-     * @param Transaction $transaction The transaction to reset.
-     * @return bool Returns true if the confirmation was reset, false otherwise.
-     */
     public function safeResetConfirm(Transaction $transaction): bool;
 
     /**
-     * Force confirm the transaction.
-     *
-     * This method forces the confirmation of the given transaction even if it is already confirmed.
-     * If the transaction is already confirmed, a `ConfirmedInvalid` exception will be thrown.
-     * If the transaction does not belong to the wallet, a `WalletOwnerInvalid` exception will be thrown.
-     * If the transaction was not found, a `RecordNotFoundException` will be thrown.
-     *
-     * @param Transaction $transaction The transaction to confirm.
-     * @return bool Returns true if the transaction was confirmed, false otherwise.
-     *
      * @throws ConfirmedInvalid         If the transaction is already confirmed.
      * @throws WalletOwnerInvalid       If the transaction does not belong to the wallet.
      * @throws RecordNotFoundException If the transaction was not found.

src/Interfaces/Confirmable.php

@@ -6,21 +6,5 @@
 
 interface ProductLimitedInterface extends ProductInterface
 {
-    /**
-     * Check if the customer can buy the product.
-     *
-     * @param Customer $customer The customer entity
-     * @param int $quantity The quantity of the product to buy. Default is 1.
-     * @param bool $force Flag to force the purchase. Default is false.
-     * @return bool Returns true if the customer can buy the product, false otherwise.
-     *
-     * The method checks if the customer can buy the product based on the quantity and the force flag.
-     * If the force flag is set to true, the method returns true regardless of the quantity.
-     * If the force flag is set to false, the method returns true if the quantity of the product is
-     * greater than or equal to the quantity to buy.
-     *
-     * The method does not check if the customer has already bought the product. It is the responsibility
-     * of the caller to check if the customer has already bought the product.
-     */
     public function canBuy(Customer $customer, int $quantity = 1, bool $force = false): bool;
 }

src/Interfaces/ProductLimitedInterface.php

@@ -12,19 +12,16 @@
 use Bavix\Wallet\Internal\Exceptions\TransactionFailedException;
 use Bavix\Wallet\Models\Transaction;
 use Bavix\Wallet\Models\Transfer;
+use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\HasMany;
 use Illuminate\Database\Eloquent\Relations\MorphMany;
 use Illuminate\Database\RecordsNotFoundException;
 
 interface Wallet
 {
     /**
-     * Deposit the specified amount of money into the wallet.
-     *
-     * @param int|non-empty-string $amount The amount to deposit.
-     * @param array<mixed>|null $meta Additional information for the transaction.
-     * @param bool $confirmed Whether the transaction is confirmed or not.
-     * @return Transaction The created transaction.
+     * @param int|non-empty-string $amount
+     * @param array<mixed>|null $meta
      *
      * @throws AmountInvalid If the amount is invalid.
      * @throws RecordsNotFoundException If the wallet is not found.
@@ -34,12 +31,8 @@ interface Wallet
     public function deposit(int|string $amount, ?array $meta = null, bool $confirmed = true): Transaction;
 
     /**
-     * Withdraw the specified amount of money from the wallet.
-     *
-     * @param int|non-empty-string $amount The amount to withdraw.
-     * @param array<mixed>|null $meta Additional information for the transaction.
-     * @param bool $confirmed Whether the transaction is confirmed or not.
-     * @return Transaction The created transaction.
+     * @param int|non-empty-string $amount
+     * @param array<mixed>|null $meta
      *
      * @throws AmountInvalid If the amount is invalid.
      * @throws BalanceIsEmpty If the balance is empty.
@@ -51,12 +44,8 @@ public function deposit(int|string $amount, ?array $meta = null, bool $confirmed
     public function withdraw(int|string $amount, ?array $meta = null, bool $confirmed = true): Transaction;
 
     /**
-     * Forced to withdraw funds from the wallet.
-     *
-     * @param int|non-empty-string $amount The amount to withdraw.
-     * @param array<mixed>|null $meta Additional information for the transaction.
-     * @param bool $confirmed Whether the transaction is confirmed or not.
-     * @return Transaction The created transaction.
+     * @param int|non-empty-string $amount
+     * @param array<mixed>|null $meta
      *
      * @throws AmountInvalid If the amount is invalid.
      * @throws RecordsNotFoundException If the wallet is not found.
@@ -66,12 +55,8 @@ public function withdraw(int|string $amount, ?array $meta = null, bool $confirme
     public function forceWithdraw(int|string $amount, ?array $meta = null, bool $confirmed = true): Transaction;
 
     /**
-     * Transfer funds from this wallet to another.
-     *
-     * @param self $wallet The wallet to transfer funds to.
-     * @param int|non-empty-string $amount The amount to transfer.
-     * @param ExtraDtoInterface|array<mixed>|null $meta Additional information for the transaction.
-     * @return Transfer The created transaction.
+     * @param int|non-empty-string $amount
+     * @param ExtraDtoInterface|array<mixed>|null $meta
      *
      * @throws AmountInvalid If the amount is invalid.
      * @throws BalanceIsEmpty If the balance is empty.
@@ -83,17 +68,8 @@ public function forceWithdraw(int|string $amount, ?array $meta = null, bool $con
     public function transfer(self $wallet, int|string $amount, ExtraDtoInterface|array|null $meta = null): Transfer;
 
     /**
-     * Safely transfers funds from this wallet to another.
-     *
-     * This method attempts to transfer funds from this wallet to another wallet.
-     * If an error occurs during the process, null is returned.
-     *
-     * @param self $wallet The wallet to transfer funds to.
-     * @param int|non-empty-string $amount The amount to transfer.
-     * @param ExtraDtoInterface|array<mixed>|null $meta Additional information for the transaction.
-     *                                                This can be an instance of an ExtraDtoInterface
-     *                                                or an array of arbitrary data.
-     * @return null|Transfer The created transaction, or null if an error occurred.
+     * @param int|non-empty-string $amount
+     * @param ExtraDtoInterface|array<mixed>|null $meta
      *
      * @throws AmountInvalid If the amount is invalid.
      * @throws BalanceIsEmpty If the balance is empty.
@@ -109,18 +85,8 @@ public function safeTransfer(
     ): ?Transfer;
 
     /**
-     * Forces a transfer of funds from this wallet to another, bypassing certain safety checks.
-     *
-     * This method is intended for use in scenarios where a transfer must be completed regardless of
-     * the usual validation checks (e.g., sufficient funds, wallet status). It is critical to use this
-     * method with caution as it can result in negative balances or other unintended consequences.
-     *
-     * @param self $wallet The wallet instance to which funds will be transferred.
-     * @param int|non-empty-string $amount The amount of funds to transfer. Can be specified as an integer or a string.
-     * @param ExtraDtoInterface|array<mixed>|null $meta Additional metadata associated with the transfer. This
-     * can be used to store extra information about the transaction, such as reasons for the transfer or
-     * identifiers linking to other systems.
-     * @return Transfer Returns a Transfer object representing the completed transaction.
+     * @param int|non-empty-string $amount
+     * @param ExtraDtoInterface|array<mixed>|null $meta
      *
      * @throws AmountInvalid If the amount specified is invalid (e.g., negative values).
      * @throws RecordsNotFoundException If the target wallet cannot be found.
@@ -136,60 +102,34 @@ public function forceTransfer(
     ): Transfer;
 
     /**
-     * Checks if the wallet can safely withdraw the specified amount.
-     *
-     * @param int|non-empty-string $amount The amount to withdraw.
-     * @param bool $allowZero Whether to allow withdrawing when the balance is zero.
-     * @return bool Returns true if the wallet can withdraw the specified amount, false otherwise.
+     * @param int|non-empty-string $amount
      */
     public function canWithdraw(int|string $amount, bool $allowZero = false): bool;
 
     /**
-     * Returns the balance of the wallet as a string.
-     *
-     * The balance is the total amount of funds held by the wallet.
-     *
-     * @return non-empty-string The balance of the wallet.
+     * @return non-empty-string
      */
     public function getBalanceAttribute(): string;
 
-    /**
-     * Returns the balance of the wallet as an integer.
-     *
-     * @return int The balance of the wallet. This value is the result of
-     *             {@see getBalanceAttribute()} converted to an integer.
-     */
     public function getBalanceIntAttribute(): int;
 
     /**
-     * Represents a relationship where a wallet has many transactions.
-     *
-     * @return HasMany<Transaction> A collection of transactions associated with this wallet.
+     * @return HasMany<Transaction, self>
      */
     public function walletTransactions(): HasMany;
 
     /**
-     * Returns all the transactions associated with this wallet.
-     *
-     * This method returns a morph many relationship that represents all the transactions
-     * associated with this wallet. The transactions may be of different types, such as
-     * deposits, withdrawals, or transfers.
-     *
-     * @return MorphMany<Transaction> A collection of transactions associated with this wallet.
+     * @return MorphMany<Transaction, Model>
      */
     public function transactions(): MorphMany;
 
     /**
-     * Returns all the transfers sent by this wallet.
-     *
-     * @return HasMany<Transfer> A collection of transfers sent by this wallet.
+     * @return HasMany<Transfer, self>
      */
     public function transfers(): HasMany;
 
     /**
-     * Returns all the transfers received by this wallet.
-     *
-     * @return HasMany<Transfer> A collection of transfers received by this wallet.
+     * @return HasMany<Transfer, self>
      */
     public function receivedTransfers(): HasMany;
 }