Laravel Wallet Warmup Laravel Package

Product Decisions This Supports

• Build vs. buy for balance reconciliation. This is a single-purpose companion to bavix/laravel-wallet: it warms/recalculates wallet balances that are stored as cached or denormalized values. If we already depend on laravel-wallet, adopting it is materially cheaper than writing and maintaining our own reconciliation command, tests, and CI matrix.
• Shipping balance-dependent features with confidence. Any roadmap item that reads a spendable balance (checkout, payouts, refunds, promo credits, top-ups) inherits a correctness risk from balance drift. A warmup/recalculation utility gives us a cheap operational lever — scheduled runs, post-migration backfills, post-deploy cache warming — rather than a product rewrite.
• Dependency-freshness / upgrade sequencing. 4.0.0 exists primarily to add support for laravel-wallet 12 and to bump CI and dev tooling. That makes the decision here a sequencing question: we adopt 4.0.0 when the wallet core goes to 12, not before. It also signals the maintainer is still actively tracking upstream — a positive signal for a dependency we'd put in the money path.
• Incident response and support posture. A reconciliation tool converts "customer claims their balance is wrong" from an engineering investigation into a routine, auditable operation — worth pricing into support and on-call expectations.
• Explicit non-decision: this is not a ledger, payments product, or source-of-truth accounting system. It does not remove the need for proper transaction records or audit trails; treat it as a repair/consistency tool layered on top of them.

When to Consider This Package

Consider adopting when:

• We already run bavix/laravel-wallet and store balances in a cached/aggregated form that can drift from the underlying transaction history.
• We need periodic reconciliation, backfill after a data migration or bulk import, or cache warming after deploys and environment refreshes.
• The alternative is an in-house artisan command plus its own tests and maintenance — a poor use of engineering time for a well-bounded problem.
• We can pin and test it against our exact wallet core version; the surface area is small enough that a staging validation is a day, not a sprint.

Look elsewhere when:

• We are not on bavix/laravel-wallet — there is no value here in isolation.
• We need general-purpose queue/cache warmup or framework-level performance tooling; this is wallet-specific.
• We need audit-grade, event-sourced ledger guarantees — that is a different (and much larger) decision.
• We are pinned to laravel-wallet < 12 and cannot move: 4.0.0 is a major bump aligned to wallet 12, so stay on the 3.x line and treat upgrades as blocked until the core moves.
• Volume/tenancy requirements exceed what a single reconciliation command comfortably handles; validate chunking and runtime against our largest tenant before committing.

Reading 4.0.0 correctly: the changelog is almost entirely Dependabot noise — phpunit/phpunit ^10.5 → ^11.0 and GitHub Actions bumps are development/CI-only and carry no runtime impact. The one substantive line is "add support laravel-wallet 12." The major version number is therefore a compatibility signal, not a feature release: expect changed Composer constraints (wallet major, and plausibly PHP/Laravel minimums). Nothing here is a deprecation of our own code, but nothing here is a reason to upgrade early either.

How to Pitch It (Stakeholders)

For executives: This is inexpensive insurance for wallet balances. It's a small, free, actively maintained open-source add-on that lets us recalculate and repair balances instead of debugging them by hand — directly reducing "my balance is wrong" incidents and the support cost that comes with them. Release 4.0.0 adds no new product capability; it keeps us compatible with the current version of our wallet core. The ask is small: a short compatibility spike plus a scheduled job and an alert, not a project.

For engineering: Single-purpose utility sitting on top of laravel-wallet. 4.0.0 is a maintenance release — the only functional change is laravel-wallet 12 support; the PHPUnit 11 and Actions bumps are dev/CI-only and don't touch runtime. The upgrade is a Composer constraint change plus a regression pass on the reconciliation command against our schema and data volumes. Treat it as a pinned, tested dependency: verify PHP/Laravel minimums, run it in staging against a production-shaped dataset, and wire it to a schedule with alerting before it becomes something we rely on. Low integration surface, low lock-in — the escape hatch is writing the command ourselves, which is exactly the cost we're avoiding.