Laravel Pay Pocket Laravel Package

Getting Started

1. Install the package with composer require hpwebdeveloper/laravel-pay-pocket.
2. Run setup commands:

   php artisan vendor:publish --tag="pay-pocket-migrations"
   php artisan migrate
   php artisan vendor:publish --tag="pay-pocket-wallets" --tag="config"
   

3. Implement WalletOperations interface and ManagesWallet trait in your User model:

   use HPWebdeveloper\LaravelPayPocket\Interfaces\WalletOperations;
   use HPWebdeveloper\LaravelPayPocket\Traits\ManagesWallet;
   
   class User extends Authenticatable implements WalletOperations
   {
       use ManagesWallet;
   }
   

4. Define wallet types in the published app/Enums/WalletEnums.php (e.g., case CASH = 'cash';, case BONUS = 'bonus';).
5. First use case: Deposit funds and make a purchase:

   $user->deposit('cash', 100.00, 'Initial funding');
   $user->deposit('bonus', 25.00, 'Welcome bonus');
   $logs = $user->pay(80.00, 'Order #123'); // Uses cash first, then bonus if needed
   

Implementation Patterns

• Priority-based payment flow: Define wallets in Enum in order of preference (highest priority first). The pay() method automatically consumes from highest-priority wallet down until amount is covered.
• Per-transaction tracking: Capture the Collection<WalletsLog> returned by pay() to generate itemized receipts or audit trails:

  $logs = $user->pay(50.00, 'Subscription renewal');
  $details = $logs->map(fn($log) => [
      'wallet' => $log->wallet_name,
      'amount' => $log->value,
      'balance_after' => $log->balance_after
  ])->toArray();
  

• Flexible deposit handling: Use the deposit() method for manual wallet top-ups (e.g., admin funding, rewards, refunds), optionally including descriptive notes for reconciliation.
• Facade vs model usage: Prefer direct model calls ($user->deposit()) for readability in controllers. Use the LaravelPayPocket facade for service-layer or job-based logic where model context may be indirect.
• Wallet balance reporting: Use $user->walletBalance for total spendable balance, and $user->getWalletBalanceByType('bonus') for targeted wallet checks before complex operations.

Gotchas and Tips

• Enum order = priority: Wallets are always prioritized by their order in WalletEnums. Changing the order later affects payment behavior—test thoroughly when modifying the Enum.
• Non-atomic payments: Multi-wallet payments are processed in sequence. If a wallet has insufficient funds, the system falls back to the next wallet—but there’s no rollback if a later step fails (ensure validation/availability checks precede payment).
• Transaction notes are optional but recommended: Omitting the $notes parameter is valid, but including descriptive notes (e.g., 'Refund for order #456') enables better logging, debugging, and end-user communication.
• Check wallet existence: Attempting to deposit/pay with a wallet not defined in WalletEnums throws an InvalidArgumentException. Validate user inputs against the Enum before calling methods.
• Migrations are additive: The package adds wallets and wallets_logs tables but does not modify your users table. This keeps integration non-invasive but requires careful scaling of wallets_logs (e.g., indexing, archival).
• Use enum casting in queries: When querying logs manually, use:

  WalletsLog::where('wallet_name', WalletEnums::BONUS->value)->get();
  

• Upgrade safely: Version 2.3+ returns a Collection from pay() instead of void. Existing code ignoring the return value remains compatible, but new usage should leverage this for transparency and debugging.