Weave Code
Laravel Wallet Laravel Package
bavix/laravel-wallet
Virtual wallet system for Laravel: manage balances, deposits/withdrawals, transfers, and multi-wallet support with robust transaction history and concurrency safety. Well-tested, benchmarked, and extensible for payments, loyalty points, and in-app credits.
It's easy to work with a virtual wallet.
Frequently asked questions about Laravel Wallet
- How do I install and set up bavix/laravel-wallet in a Laravel 13 project?
- Run `composer require bavix/laravel-wallet` and publish the config with `php artisan vendor:publish --tag=laravel-wallet-config`. Then, run the migrations (`php artisan migrate`) to create the wallets and transactions tables. The package includes a `WalletServiceProvider` that auto-registers core services. Check the [official documentation](https://bavix.github.io/laravel-wallet/guide/introduction/) for step-by-step setup.
- Does this package support multi-wallet systems (e.g., user + team wallets) out of the box?
- Yes, the package supports multi-wallet systems via the `HasWallets` trait and `Wallet` model. You can assign multiple wallets to a single entity (e.g., a user or team) and manage balances independently. For complex setups, use the `Wallet::createFor()` method or extend the `Wallet` model. The [extensions guide](https://bavix.github.io/laravel-wallet/guide/extensions/) covers advanced use cases.
- What Laravel and PHP versions are officially supported by bavix/laravel-wallet?
- The package supports Laravel 11.x–13.x and PHP 8.3–8.5. Laravel 10 is not officially supported due to PHP 8.2 limitations. Check the [support policy](https://github.com/bavix/laravel-wallet#support-policy) for version-specific release dates and end-of-support timelines. Always align your Laravel version with the package’s matrix to avoid compatibility issues.
- How does bavix/laravel-wallet handle concurrency issues like race conditions in high-traffic apps?
- The package uses Redis locks by default to prevent race conditions during wallet operations (e.g., deposits, withdrawals). For production, enable Redis in the `wallet.php` config under `lock`. If Redis isn’t available, fall back to database locks, though performance may degrade under high load. The [benchmark tests](https://github.com/bavix/laravel-wallet-benchmark/) demonstrate scalability with proper lock configurations.
- Can I integrate bavix/laravel-wallet with Stripe or PayPal for real-world payments?
- Yes, you can use the package alongside Stripe/PayPal by treating external payments as wallet deposits or withdrawals. For example, after a Stripe charge succeeds, call `Wallet::deposit($userId, $amount)`. The package doesn’t include payment gateway logic but provides hooks (e.g., `wallet.created` events) to sync with external systems. Extend the `WalletService` to add custom logic for reconciliation.
- How do I test wallet functionality in Laravel unit tests? Does the package include mocking support?
- The package doesn’t include built-in test doubles, but you can mock wallet interactions using Laravel’s `Mockery` or `PHPUnit` factories. Create a `Wallet` facade mock or use interfaces like `WalletInterface` to isolate dependencies. For integration tests, use the `WalletTestCase` provided in the package’s test suite. The [testing guide](https://bavix.github.io/laravel-wallet/guide/testing/) covers best practices for unit and feature tests.
- What are the performance benchmarks for bavix/laravel-wallet, and when should I use Redis?
- Benchmark tests show the package handles ~500–1000 transactions per second (TPS) on a single database instance without Redis. For higher loads (>1000 TPS), enable Redis locks to avoid deadlocks and reduce database contention. The package’s `balanceInt` field ensures precision, but floating-point operations may require additional caching. Monitor `wallet.php` settings for `lock` and `cache` to optimize performance.
- How can I extend bavix/laravel-wallet to add custom validation rules (e.g., blacklisted transactions)?
- Extend the `Wallet` model or create a custom service binding for `WalletValidator`. Override the `canDeposit()` or `canWithdraw()` methods to add logic (e.g., check against a blacklist table). Use Laravel’s policy system or middleware to enforce rules before transactions. The [extensions guide](https://bavix.github.io/laravel-wallet/guide/extensions/) includes examples for custom validation and event listeners.
- Are there alternatives to bavix/laravel-wallet for Laravel wallet systems, and what makes this package unique?
- Alternatives include `spatie/laravel-money` (for currency handling) or custom solutions using Eloquent. However, `bavix/laravel-wallet` stands out with built-in transaction ledgers, multi-wallet support, and benchmark-tested performance. It also includes mutation testing (via Stryker) and a clear upgrade path. The package’s focus on auditing and extensibility (e.g., `ProductInterface`) makes it ideal for fintech or SaaS applications.
- How do I handle wallet migrations in a production environment with zero downtime?
- Use Laravel’s `migrate:fresh` or `migrate:status` to avoid conflicts, and test migrations in a staging environment first. For large-scale apps, consider a blue-green deployment: deploy the new wallet schema alongside the old one, then switch traffic gradually. The package’s migrations are backward-compatible within major versions, but always back up your database before running `php artisan migrate`. Check the [upgrade guide](https://bavix.github.io/laravel-wallet/#/upgrade-guide) for version-specific steps.
Weaver
How can I help you explore Laravel packages today?