Laravel Wallet Laravel Package

Technical Evaluation

Architecture Fit

• Core Use Case Alignment: The package excels in virtual wallet management (deposits, withdrawals, fractional transactions, refunds) and purchase workflows (e.g., e-commerce, subscriptions). It aligns well with:
  • Monetization systems (e.g., SaaS, marketplaces, gaming).
  • Prepaid models (e.g., credits, loyalty programs, microtransactions).
  • Multi-currency or multi-wallet setups (via extensions like HasWalletFloat).
• Extensibility: The package supports custom transaction logic (e.g., PurchaseServiceInterface, PurchaseQueryHandlerInterface) and merchant fees, making it adaptable to complex billing scenarios.
• Database Agnostic: Works with Laravel’s Eloquent, enabling integration with existing models (e.g., User, Product) without schema changes.
• Limitations:
  • No built-in fraud detection (requires custom validation via canBuy() or external services).
  • No native support for external payment gateways (e.g., Stripe, PayPal) — transactions are wallet-to-wallet.
  • Multi-wallet support is available but requires explicit configuration (e.g., wallets() relationship).

Integration Feasibility

• Laravel Ecosystem Fit: Designed for Laravel 11–13, with PHP 8.3–8.5 support. Leverages Laravel’s service container, events, and Eloquent, reducing friction.
• Migration Path:
  • Minimal Boilerplate: Add traits (HasWallet, CanPay) to models and configure the package via config/wallet.php.
  • Backward Compatibility: Supports gradual adoption (e.g., start with balanceInt before enabling balanceFloat).
• Dependencies:
  • Core: illuminate/database, bavix/laravel-wallet (no heavy external deps).
  • Extensions: Optional (e.g., bavix/laravel-wallet-swap for exchange rates).
• Testing: Includes PHPUnit tests, mutation testing, and benchmarking, but custom logic may need additional test coverage.

Technical Risk

• Transaction Consistency:
  • Race Conditions: High-concurrency scenarios (e.g., simultaneous pay() calls) may require database transactions or optimistic locking (e.g., lockForUpdate()).
  • Atomicity: The package uses Laravel’s DB transactions, but custom logic (e.g., canBuy()) must be wrapped in transactions to avoid partial updates.
• Floating-Point Precision:
  • Uses Brick Math for accurate decimal arithmetic, but edge cases (e.g., rounding) may need validation.
  • Mitigation: Test with extreme values (e.g., 0.1 + 0.2 != 0.3).
• Performance:
  • N+1 Queries: Eager loading (with('wallet')) is recommended for purchase workflows.
  • Multi-Wallet Overhead: Querying multiple wallets per user may impact performance in high-scale apps.
• Customization Risk:
  • Overriding core services (e.g., PurchaseService) requires deep understanding of the package’s architecture.
  • Mitigation: Use dependency injection to mock services during development.

Key Questions for Stakeholders

1. Business Logic:
   • Are there custom validation rules for purchases (e.g., user tiers, blacklists) beyond canBuy()?
   • How should failed transactions (e.g., insufficient funds) be handled (retries, notifications)?
2. Scalability:
   • Will the system support millions of transactions/day? If so, consider:
     • Caching (e.g., Redis for balance checks).
     • Queueing (e.g., Laravel Queues for async withdrawals/deposits).
3. Audit & Compliance:
   • Are transaction logs required for regulatory purposes? The package lacks built-in audit trails (consider adding observers or events).
4. Multi-Currency:
   • Is multi-currency support needed? The package supports fractional amounts but not currency conversion (use extensions like swap).
5. Legacy Systems:
   • How will this integrate with existing payment systems (e.g., Stripe, legacy databases)?

Integration Approach

Stack Fit

• Laravel-Centric: Optimized for Laravel’s ecosystem (Eloquent, Service Container, Events).
  • Pros: Seamless integration with existing auth (User models), validation, and middleware.
  • Cons: Not framework-agnostic (e.g., cannot use with Symfony or plain PHP).
• Database Compatibility:
  • Works with MySQL, PostgreSQL, SQLite (via Eloquent).
  • Valkey (Redis) support added in v12.0.0 for caching (e.g., wallet:balance).
• Tech Stack Synergy:
  • PHP 8.3+: Leverages typed properties, enums, and attributes.
  • Composer: Zero-config installation (composer require bavix/laravel-wallet).
  • Testing: Compatible with Laravel’s testing tools (Pest, PHPUnit).

Migration Path

1. Pilot Phase (Low Risk):
   • Step 1: Integrate HasWallet into a non-critical model (e.g., TestUser).
   • Step 2: Test basic transactions (deposit(), withdraw()) and fractional amounts (HasWalletFloat).
   • Step 3: Validate with edge cases (e.g., negative balances, zero amounts).
2. Core Integration (Medium Risk):
   • Step 4: Apply CanPay to User and Product models.
   • Step 5: Implement purchase workflows (pay(), refund()) and test with a mock cart.
   • Step 6: Add custom validation (e.g., canBuy() logic) and transaction observers for logging.
3. Production Rollout (High Risk):
   • Step 7: Enable for high-value transactions (e.g., subscriptions) with monitoring (e.g., Sentry for errors).
   • Step 8: Gradually replace legacy payment logic (e.g., Stripe webhooks → wallet events).

Compatibility

• Laravel Versions:
  • v12.x: Laravel 13 (PHP 8.3–8.5).
  • v11.x: Laravel 11–13 (deprecated after May 2026).
  • Action: Upgrade to v12.x for long-term support.
• PHP Extensions:
  • Requires BCMath or GMP for high-precision math (enabled by default in PHP).
  • Valkey (Redis): Optional for caching (v12.0.0+).
• Third-Party Conflicts:
  • Low Risk: Minimal external dependencies. Potential conflicts with:
    • Other wallet packages (e.g., spatie/laravel-money).
    • Custom balance columns (rename conflicts; package uses wallet_balance).

Sequencing

Operational Impact

Maintenance

• Package Updates:
  • Proactive: Follow the upgrade guide for breaking changes (e.g., v11 → v12).
  • Automated: Use Dependabot or GitHub Actions to monitor updates.
• Custom Logic:
  • High Maintenance: Overriding core services (e.g., PurchaseService) requires documentation and testing.