Laravel Wallet Warmup Laravel Package

Getting Started

bavix/laravel-wallet-warmup is a repair/backfill tool for bavix/laravel-wallet: it recomputes a wallet's stored balance by replaying the transaction ledger, so a wallet whose amount drifted (failed job, manual DB tweak, half-imported history) can be brought back in sync with its transactions.

composer require bavix/laravel-wallet-warmup

Version 4.0.0 targets laravel-wallet ^12 (and PHPUnit ^11 in dev), so it transitively demands PHP 8.2+ and a Laravel version supported by wallet 12. If your app is pinned to laravel-wallet 11 or below / PHP 8.1, stay on 3.0.1 — this is a major bump precisely because the underlying wallet package moved.

Where to look first, in order:

1. The WarmUp facade (or the injected warmup service) — the single-wallet entry point. This is 90% of real usage.
2. The console command (php artisan wallet:warmup) — the bulk/reconciliation entry point; read its signature and options before running it anywhere.
3. The service provider / published config, if any — chunk size, queue connection, and whether the command is registered by default.

First real use case: pick one known-broken wallet on staging, snapshot the row, run the single-wallet warmup in tinker, and diff balance against SELECT SUM(amount) FROM transactions WHERE wallet_id = ?. Confirm the numbers match before you let it near production.

Implementation Patterns

Targeted repair in an admin action. Don't reach for the bulk command when one wallet is off. Wrap the single-wallet call in your own artisan command or Filament/Nova action so it's auditable, e.g. WarmUp::warmup($wallet) inside a DB::transaction() with a Log::info of before/after balances. Give support staff a button, not shell access.

Post-import reconciliation. If you backfill historical transactions (legacy ledger import, data migration from another system), the wallets' cached balances won't reflect the newly inserted rows. Sequence it as: import transactions (via the wallet API, not raw inserts) → run warmup for the affected wallets → assert the sum matches. Key the warmup to the specific wallet IDs you touched rather than the whole table.

Drift detection instead of blanket recalc. On a large install, warming up every wallet nightly is wasteful. Add a scheduled job that runs a cheap aggregate query (SUM(amount) grouped by wallet_id vs wallets.balance) and only warms up the mismatches. That turns a maintenance-window operation into a routine, low-cost safety net, and gives you a metric (number of drifted wallets) that is itself worth alerting on.

Queue it for bulk runs. Chunk by wallet ID and dispatch one job per batch, with $timeout and $tries set explicitly. This keeps memory flat and lets you throttle against a replica if the transactions table is huge. Make the job idempotent — it is, by nature, so retries are safe.

Gate the rollout. For a one-off correction after a bug fix, ship warmup behind a feature flag and a dedicated command (php artisan wallets:repair --ids=...), run it on a handful of accounts, verify, then widen. Record the wallet IDs you processed so a re-run can skip them.

Pair with, don't replace, wallet's own tooling. Warmup only rewrites balances from the ledger. It will not fix a corrupt transaction row, a mismatched refund flag, or a wallet whose currency is wrong. Treat it as the last step in a repair runbook, not the whole runbook.

Gotchas and Tips

• The upgrade is the breaking change. 4.0.0 = laravel-wallet ^12 + PHPUnit ^11. Nothing in the release notes changes the public surface, but the transitive constraint jump will break composer update on older apps. Check composer why-not bavix/laravel-wallet-warmup 4.0.0 before assuming it's a drop-in.
• Manual balance edits are destroyed. Warmup derives balance from transactions. Any value you set with forceFill, raw SQL, or a seeded wallet with no ledger entries behind it will be overwritten — possibly to 0. If a balance must survive, it needs a corresponding transaction first.
• Wallets with no transactions. Verify explicitly what happens to an empty wallet: it should stay at its starting balance or go to zero depending on config. Test this case; it's the one that silently zeroes accounts.
• Integer minor units. laravel-wallet stores amounts as integers. Never let a float or a formatted decimal string into the recompute path — you'll get rounding drift that looks like the bug you were fixing.
• Concurrency. Warming up a wallet while a payment is mid-flight can write a stale balance over a fresh one. Use a cache/DB lock per wallet or run it in a window with writes paused. The recompute is not a substitute for the wallet's own locking.
• Long runtimes on big ledgers. Watch MySQL connection time and PHP max_execution_time; batch size is the knob. On very large tables, run the drift query against a read replica and only warm up primary for the mismatched rows.
• Idempotency is your test. Run the warmup twice on staging — the second run should be a no-op with identical balances. If it isn't, your ledger has a problem the warmup can't fix, and the drift will come back.
• Verify outside the tool. Don't trust a zero exit code. After a run, re-run the SUM(amount) vs balance comparison query across the affected IDs; that's your actual acceptance test.
• Don't schedule it aggressively. This is a repair tool, not a real-time invariant. Hourly or nightly drift checks are plenty; every-minute crons on a hot transactions table will show up in your slow query log.
• Multi-wallet models. A model can hold several wallets (per currency, per type). Iterate all of them, not just $user->wallet — the drift is often in the secondary one nobody looks at.
• Extension points before vendor patches. If you need custom behaviour (custom chunking, custom logging), check for published config and events first. Forking this package is a bad trade — it exists to be a thin, boring layer over the wallet ledger.