Laravel Wallet Warmup Laravel Package

Technical Evaluation

Architecture fit. bavix/laravel-wallet-warmup is a narrow companion package to bavix/laravel-wallet; it does not stand alone. Its architectural role is to pre-compute/cache wallet balance aggregates so reads do not hit the ledger on every request. That makes it a performance-sidecar, not a domain component — a favourable fit for teams already standardized on laravel-wallet, and a non-starter for anyone who is not. 4.0.0 adds support for laravel-wallet 12, which is the only functional change in the release.

Integration feasibility. Low effort in principle: a composer require, a config publish, and scheduling the warmup command/job. The real cost is dependency alignment — 4.0.0 pins the package to the wallet 12 line, so adoption is gated on the host application already running (or being ready to run) laravel-wallet 12. The PHPUnit ^11.0 bump is a dev-only constraint but signals a raised PHP floor (PHP 8.2+) for the package's own toolchain; confirm the runtime composer.json requirement before assuming parity with your PHP version.

Technical risk. Moderate and mostly transitive. The major version number is almost certainly driven by the upstream laravel-wallet 12 major rather than by internal redesign — the changelog contains no feature or API changes of its own. That means the breaking-change surface lives in the wallet package (schema, model contracts, balance calculation semantics), and warmup inherits it. Residual risks: (a) warmup caches can silently diverge from ledger truth if wallet 12 changed how balances are computed or invalidated; (b) the release notes are dependabot-dominated, so there is little prose describing upgrade steps — treat the diff, not the notes, as the source of truth; (c) small-maintainer, bus-factor-1 project with an automated release pipeline.

Key questions.

1. Does laravel-wallet 12 introduce schema migrations or balance-semantics changes that invalidate previously warmed caches?
2. What is the package's declared PHP and Laravel support matrix in 4.0.0's composer.json (the notes do not say)?
3. Is there a documented upgrade guide from 3.x, or is the 3.0.1→4.0.0 diff the only reference?
4. Are warmup artifacts (tables/cache keys) versioned, and is there a safe rebuild/backfill path after upgrade?
5. Do we even need warmup, or is this a premature optimization for our read volume?

Integration Approach

Stack fit. Assumes Laravel + Eloquent + bavix/laravel-wallet 12. If the application is on wallet 11 or earlier, this release does not apply. Confirm Laravel version compatibility from the package's composer.json — the release notes only enumerate CI actions, not framework constraints.

Migration path. Sequenced, not simultaneous:

1. Inventory current laravel-wallet version and any wallet schema in use.
2. Read the laravel-wallet 12 upgrade guide first — that is where the real breaking changes are. Plan the wallet upgrade as its own change.
3. Once wallet 12 is stable in staging, bump laravel-wallet-warmup to ^4.0 and run composer update bavix/laravel-wallet-warmup --with-dependencies.
4. Publish/republish config (vendor:publish) and diff against the existing config — major bumps frequently add or rename keys.
5. Rebuild warmup caches from scratch rather than trusting carried-over data; verify a sample of warmed balances against raw ledger sums.

Compatibility. Pin ^4.0 explicitly; do not allow a floating constraint that could straddle the wallet 11/12 boundary. Verify PHP runtime ≥ 8.2 to match the toolchain expectation, and check that your test suite's PHPUnit version coexists (the package's ^11.0 is dev-only and should not conflict, but a shared monorepo can surface it).

Sequencing. Wallet upgrade → verification → warmup upgrade → cache rebuild → read-path validation. Budget a rollback that includes cache invalidation, not just a composer revert, since stale warmed balances can persist after a code rollback.

Operational Impact

Maintenance. Low touch, but not zero. The project is dependabot-driven with automated changelog and GPG-signed releases — good hygiene, thin human-authored documentation. Expect to self-serve upgrade guidance from diffs. Budget a recurring line item for dependency review at each wallet major.

Support. Single-maintainer (rez1dent3 / bavix) with a small ecosystem of companion packages. No commercial support path. Acceptable for a non-critical read-optimization layer; a poor fit for anything on the transactional critical path.

Scaling. Warmup shifts cost from read-time aggregation to scheduled batch work. It scales reads well and scales writes/ledger complexity poorly — as transaction volume grows, warmup jobs lengthen and the staleness window widens. Model the job duration against your peak ledger write rate before committing.

Failure modes.

• Silent staleness: warmup job fails or is delayed, reads return stale balances with no error. Needs freshness monitoring, not just job-success alerting.
• Semantic drift: wallet 12 changes balance calculation; warmup still runs but computes the old value. The highest-severity risk in this upgrade and the hardest to detect.
• Post-rollback corruption: code reverted, caches not rebuilt, mismatched artifacts.
• Dependency deadlock: pinned to wallet 12 while another package still requires 11.

Ramp-up. Small for an engineer already fluent in laravel-wallet — the package is a thin layer with a command and a config file. The genuine ramp-up cost is in the wallet 12 upgrade itself, not in warmup. Allocate effort proportionally: ~80% wallet 12 migration and cache-rebuild verification, ~20% warmup package mechanics.