Laravel Wallet Laravel Package

Technical Evaluation

Architecture fit

• The package is model-centric, not service-centric: value is delivered by attaching HasWallet / CanPay / HasWalletFloat traits and Wallet / Customer / ProductInterface contracts to existing Eloquent models. This is a good fit for a Laravel codebase that already has User, Order, and Item aggregates — it avoids introducing a parallel domain entity and a synchronization problem with our own tables.
• The persisted shape is conventional and auditable: a wallets table keyed by a polymorphic holder (holder_type, holder_id) plus a slug for multi-wallet, a transactions ledger with payable morphs and a confirmed flag, and a separate transfers record for holder-to-holder movement. That maps cleanly onto the reports and reconciliations a finance stakeholder will inevitably request.
• Money is stored as integer minor units with per-wallet decimal_places, with brick/math for arithmetic and an optional float-facing trait (balanceFloat). This is the correct default for a wallet system; the risk is that the float surface is available at all and gets used inside business logic.
• Concurrency is delegated to a bookkeeper cache/lock layer (WALLET_CACHE_DRIVER, WALLET_CACHE_TTL, WALLET_LOCK_DRIVER, WALLET_LOCK_TTL since 10.x). This is the single most important architectural decision in the package and the one a TPM must insist on load-testing before commitment. Correctness of balances depends on our Redis/lock configuration, not just on the library.

Integration feasibility

• Baseline path is short: composer require bavix/laravel-wallet, publish and run migrations, add traits + interfaces to the User model, then deposit / withdraw / pay / refund work. A spike should reach a working balance in under a day.
• The purchase path is where effort concentrates. Implementing ProductInterface (unlimited) or ProductLimitedInterface (limited) is straightforward, but the docs explicitly warn against the limited interface for shopping carts due to N-query behavior and recommend overriding PurchaseServiceInterface instead. Any cart/checkout flow will need that work plus a bulk availability check.
• The External API (PurchaseQuery / PurchaseQueryHandlerInterface, transaction and transfer UUIDs) provides the idempotency hooks we need for retry-safe payment endpoints — this is a meaningful de-risking feature that should be treated as mandatory rather than optional.
• Optional extensions are separable and can be deferred: laravel-wallet-uuid (UUID model keys), laravel-wallet-swap (FX rates — defer unless multi-currency is in scope), laravel-wallet-warmup (balance refresh, useful if we hit drift).

Technical risk

• Reconciliation risk (highest). Balance is materialized/cached alongside ledger rows. Any cache eviction, driver failover, or partial write can desynchronize wallets.balance from the transaction sum. We need a scheduled reconcile-and-repair job and an alert on drift from day one, not post-launch.
• Double-spend risk. Locking is configuration-dependent. Misconfigured or undersized lock TTL silently converts into an overdraft. This must be validated with a concurrent-write test, not code review.
• Intentional overdraft. forceWithdraw permits negative balances by design. That is a policy lever, not a bug, and it needs an explicit product decision plus an authorization wrapper in our code.
• Version coupling. Per the support policy, 12.x requires Laravel ^13.0 and PHP 8.3–8.5; 11.x covers Laravel 11–13 but its end-of-improvements is May 2026. If we are on Laravel 10/11 today we are adopting a branch with a near-term expiry, so the upgrade path to 12.x (and Laravel 13) must be planned at adoption time.
• API churn inside majors. The 10.x notes show contract changes (e.g., BookkeeperServiceInterface::missing → forget, MorphMany → HasMany on transfers, removed LockProviderNotFoundException). Semver is respected for majors but not all breaking behavior waits for one.
• Dependency-review signals are weak. ~1.3k stars, score ~45/100, opportunity ~32, a single primary maintainer (rez1dent3), and 0 listed dependents. The dependent count is likely a dataset artifact, but it cannot be used as evidence of ecosystem validation. MIT license is fine; bus-factor risk is not.
• Data quality caveat. The record's "last release 2026-10-22" is inconsistent with the support table's 12.x release date (Apr 2026) and with the release notes supplied (12.0.4 → 12.1.0). Treat all version/date claims as unverified until confirmed against Packagist directly.
• Schema-change risk. 12.1.0 drops four redundant indexes on transactions and wallets and reports index size 685 → 329 MB (MySQL) and insert of 50k rows −63%. The win is real, but the migration runs DROP INDEX — on a high-write table this needs pt-online-schema-change / DROP INDEX CONCURRENTLY plus manual migrations table bookkeeping, as the release note itself says.

Key questions

1. Is our wallet use case custodial balance tracking (deposit/withdraw/transfer) or checkout payment orchestration (pay/refund/cart)? The second requires PurchaseServiceInterface work the first does not.
2. What is the required money model — single currency, per-wallet slug segmentation, or true multi-currency with FX? Only the third pulls in laravel-wallet-swap.
3. What are our current Laravel and PHP versions, and which support branch (11.x vs 12.x) are we committing to, with what re-upgrade date?
4. Which cache and lock drivers are available in production, and what TTL/concurrency envelope have we proven under load?
5. Can balances ever go negative in our product (forceWithdraw), and who authorizes it?
6. Do we need per-transaction idempotency keys across our public API, and are we adopting the External API UUIDs for that?
7. What is our reconciliation cadence and tolerance for drift, and who owns the repair runbook?
8. Is a single-maintainer dependency acceptable here, or do we need an internal fork/abstraction seam for exit?

Integration Approach

Stack fit

• Assumes Laravel (^11/^12/^13 on the 11.x branch, ^13 on 12.x), PHP 8.3+, Composer, Eloquent migrations, and a cache/lock backend (Redis strongly preferred over database or file for the lock driver). MySQL and PostgreSQL are both evidenced in the 12.1.0 index benchmarks.
• It is a library, not a service — there is no sidecar to run, no queue worker of its own, no external API surface. Operational surface area is therefore our queue, our cache, and our database.
• Fits cleanly alongside existing Laravel auth/policy, event, and job infrastructure; wallet operations emit events we can hook for notifications and audit.

Migration path

• No data migration is inherent — this is additive (new tables, new traits). The migration is one of semantics: our existing "credits/bucks/points" column, if any, must be converted to integer minor units and backfilled into a wallet, with a one-time reconciliation proving parity before cutover.
• For the schema itself: run published migrations in a scratch environment first, then in staging against a production-shaped copy, and only then in production. The 12.1.0 index-drop migration needs a manual online-schema-change plan if transactions is already large.

Compatibility

• Verify exact constraint matrix on Packagist before committing: package major ↔ Laravel major ↔ PHP minor. The 12.x line pins to Laravel ^13, which may force a framework upgrade we would not otherwise schedule this year.
• Transitive surface is modest (brick/math, doctrine/dbal historically) but must clear our dependency policy, including license and advisory scanning.
• If models use UUID primary keys, plan bavix/laravel-wallet-uuid from the start rather than retrofitting.
• If balances are exposed through an admin panel (the 10.x notes reference a Laravel Nova interaction fixed by "viewing a balance no longer creates a wallet"), confirm current behavior against our admin tooling.

Sequencing

1. Spike (1 week, one engineer). Sandbox app: deposit, withdraw, transfer, pay + refund, multi-wallet via slug, float surface, and a 200-concurrent-write test against Redis locks with a drift check.
2. Decision gate. Money model (integer units, decimal_places, currency strategy), overdraft policy, idempotency requirement, and 11.x-vs-12.x branch commitment documented and signed off by product + finance.
3. Schema and DBA review. Published migrations, index footprint estimate, online-schema-change procedure, and rollback plan.
4. Domain wiring (1–2 weeks). Traits/contracts on User and Item; purchase service override if cart flows are in scope; external API with UUID idempotency on our payment endpoints.
5. Trust layer (parallel, non-negotiable). Scheduled reconciliation job, drift alerting, lock-failure alerting, and an admin repair command. Gate launch on a green reconcile over a full business cycle.
6. Progressive rollout. Feature-flag the wallet path; run shadow mode where the legacy balance is still computed and diffed against the wallet balance for a defined window; then cut over per cohort.
7. Upgrade rehearsal. Document and dry-run the next major upgrade (11.x → 12.x, or 12.x → next) so the support-window expiry is a scheduled task, not an incident.

Operational Impact

Maintenance

• Release cadence is steady and mostly automated (Dependabot, ECS/Rector/PHPStan in the changelog), which suggests active hygiene. Majors appear roughly annual, with support windows published up front — that is unusually good governance for a package of this size and should be used to drive our calendar.
• Single-maintainer concentration is the standing maintenance risk. Mitigations: pin exact versions with a lockfile, keep wallet calls behind a thin internal service/repository seam so the package is swappable, and budget a fork-and-patch contingency.
• Budget ~1–2 engineer-days per major upgrade plus a migration review, and one planned upgrade per support-window boundary (11.x improvements end May 2026, support ends Sep 2026).

Support

• Documentation is a real VitePress site with an upgrade guide and an introduction path; there is a Telegram community channel (@laravel_wallet) rather than a formal SLA or issue-triage commitment. For anything customer-facing, we are the support tier — no vendor escalation path exists.
• Score of ~45/100 and "readme, docs, releases" as the only maturity signals means: good public documentation, no evidence of enterprise adoption, no professional support option. Plan accordingly for on-call ownership.

Scaling

• Write throughput is the meaningful axis. The 12.1.0 index reduction is quantified (index size −52% MySQL / −41% PostgreSQL; 50k-row insert −63% time / −32% time) and reads are unchanged — so on a transaction-heavy workload, adopting 12.1.0+ early is a real capacity win.
• Read scaling requires us to use with('wallet') / with('wallets') consistently; un-eager-loaded balance access is the classic N+1 in this package and will surface as a latency regression under load, not as an error.
• Lock contention scales with write concurrency on hot wallets. A single high-traffic wallet (e.g., a platform fee account) becomes a contention hot spot; design to shard or avoid it.
• Cache/lock backend becomes a hard dependency: Redis sizing and availability now directly determine whether payments succeed.

Failure modes

Ramp-up

• Learning curve is shallow for the core API (deposit/withdraw/transfer/pay/refund are one-liners) — an engineer unfamiliar with the package can be productive in 2–3 days. The expensive knowledge is not the API but the lock/cache/reconciliation model and the purchase-service override, which realistically needs 2–4 weeks to reach production confidence including the trust layer.
• Recommend one engineer own the package end-to-end (schema, locks, reconciliation) and produce a short internal runbook before the second engineer touches it. Given the single-maintainer upstream, internal documentation is the real continuity plan.