V Wallet Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require immeyti/v-wallet
   php artisan vendor:publish --provider="Immeyti\VWallet\VWalletServiceProvider" --tag="migrations"
   php artisan migrate
   

   • Focus on the --tag="migrations" flag to set up the database schema.

2. First Use Case: Creating a Wallet

   use Immeyti\VWallet\Models\Wallet;
   
   $wallet = Wallet::create([
       'user_id' => auth()->id(), // Link to a user
       'balance' => 0.00,
       'currency' => 'USD', // Default or configurable
   ]);
   

   • Verify the user_id foreign key constraint is respected.

3. Where to Look First

   • Models: app/Models/Wallet.php (or vendor/immeyti/v-wallet/src/Models/Wallet.php).
   • Migrations: database/migrations/[timestamp]_create_wallets_table.php.
   • Service Provider: Immeyti\VWallet\VWalletServiceProvider for bootstrapping events/bindings.

Implementation Patterns

Core Workflows

1. Wallet Operations

   • Deposit:

     $wallet->deposit(100.00); // Updates balance atomically
     

   • Withdrawal (with validation):

     if ($wallet->withdraw(50.00)) {
         // Success: balance updated
     } else {
         // Failed: insufficient funds or other constraints
     }
     

   • Transfer Between Wallets:

     $wallet1->transfer($wallet2, 25.00); // Atomic operation
     

2. Integration with Laravel Ecosystem

   • Events: Listen to wallet.created, wallet.deposited, etc. (check VWalletServiceProvider for event bindings).
   • Observers: Extend WalletObserver (if provided) or attach custom observers to the Wallet model.
   • Policies: Use Laravel’s authorization:

     use Immeyti\VWallet\Policies\WalletPolicy;
     
     $this->authorize('view', $wallet); // Requires WalletPolicy
     

3. API/Controller Layer

   • Resource Controller:

     namespace App\Http\Controllers;
     
     use Immeyti\VWallet\Http\Controllers\WalletController;
     use App\Http\Controllers\Controller;
     
     class CustomWalletController extends WalletController {
         // Override methods as needed (e.g., add custom validation)
     }
     

   • API Routes:

     Route::apiResource('wallets', \App\Http\Controllers\CustomWalletController::class)
          ->middleware('auth:sanctum');
     

4. Testing

   • Use createWallet() helper (if provided) or factory:

     $wallet = Wallet::factory()->create(['balance' => 1000.00]);
     

   • Test edge cases: negative balances, concurrent transactions.

Gotchas and Tips

Pitfalls

1. Beta Stage Risks

   • Avoid production use until stability is confirmed (check GitHub issues for known bugs).
   • Monitor for breaking changes in minor updates.

2. Transaction Handling

   • Race Conditions: Withdrawals/deposits must use database transactions:

     DB::transaction(function () use ($wallet) {
         $wallet->withdraw(50.00);
     });
     

   • Negative Balances: The package may not enforce hard limits by default. Add validation:

     $wallet->balance >= $amount || throw new \Exception('Insufficient funds');
     

3. Currency Support

   • Defaults to a single currency. For multi-currency, extend the Wallet model or use a trait:

     class MultiCurrencyWallet extends Wallet {
         protected $currency;
         // Custom logic for currency conversion
     }
     

4. Observer/Event Quirks

   • Events may not be fired for all operations (e.g., transfers). Verify in WalletObserver.
   • Custom events? Extend the package’s event classes or create new ones:

     event(new \Immeyti\VWallet\Events\WalletTransferAttempted($wallet1, $wallet2, $amount));
     

Debugging Tips

1. Log Transactions

   • Add a transactions table or log to wallet_logs:

     \Log::info('Wallet operation', ['wallet_id' => $wallet->id, 'action' => 'deposit', 'amount' => $amount]);
     

2. Database Constraints

   • Check for ON UPDATE CASCADE on user_id if users are soft-deleted. Add a scope:

     public function scopeActive($query) {
         return $query->whereNull('user_deleted_at');
     }
     

3. Testing Edge Cases

   • Concurrency: Use Laravel’s refreshModel() or fresh() to test race conditions.
   • Floating-Point Precision: Use bcmath or gmp for financial calculations:

     $balance = bcadd($wallet->balance, $amount, 2);
     

Extension Points

1. Custom Fields

   • Add columns to the wallets table via migration, then extend the Wallet model:

     protected $casts = [
         'is_active' => 'boolean',
         'metadata' => 'json',
     ];
     

2. Webhooks

   • Trigger external notifications by extending the WalletObserver:

     public function deposited(Wallet $wallet) {
         Http::post('https://your-service.com/webhook', [
             'event' => 'deposit',
             'amount' => $wallet->balance,
         ]);
     }
     

3. Rate Limiting

   • Limit transactions per minute/user with Laravel’s throttle middleware or a custom trait:

     use Illuminate\Cache\RateLimiter;
     
     RateLimiter::for('wallet-transactions', function () {
         return Limit::perMinute(10)->by($this->user()->id);
     });