Laravel Wallet Swap Laravel Package

Product Decisions This Supports

• Feature: offering cross-currency or cross-asset transfers without a bespoke ledger. The package adds an atomic "swap" primitive on top of bavix/laravel-wallet — a paired debit from one wallet and credit to another at a conversion rate, recorded as a first-class transaction. That turns "let users move value between two balances" from a design project into a configuration and UI decision.
• Build vs buy. If you are already on laravel-wallet, the build alternative is a custom conversion service plus reconciliation logic plus reporting that understands a new transaction shape. This package is one dependency that reuses the core transaction group, so reporting, statements and refunds keep working. Default recommendation: buy.
• Roadmap sequencing for multi-currency. Common roadmap items it unblocks: wallet-to-wallet transfers between currencies, points-to-credit exchange, prepaid balance conversion, marketplace payouts in a different currency than the sale, gift/loyalty balance consolidation. If any of these sit in "later", this is what moves them into "now".
• Commission and pricing decisions. Because a swap is a transaction type with a defined rate and a source/destination pair, product can specify fees, spread and rounding rules as policy rather than as engineering work — and can state them in customer-facing terms ("1 point = 0.01 credit, 2% conversion fee").
• Use-case shortlist worth prototyping: in-app currency exchange, loyalty/token conversion, game or virtual currencies, top-up from a bonus wallet into a spendable wallet, cross-currency refunds.

When to Consider This Package

Adopt when:

• You already run bavix/laravel-wallet and intend to stay on it. This package is an extension of that core, not a standalone wallet.
• Your wallet rows can carry different currencies (or different "asset" types) and users need to move value between them.
• You need the swap to be atomic and to appear in the same transaction/statement stream as ordinary deposits and withdrawals — that is the main reason to pick this over a hand-rolled service.
• You need an auditable record of rate plus source and destination for each conversion.

Version gate — the substance of 8.0.0: this release exists to support laravel-wallet 12. Everything else in the notes is CI and dependency housekeeping. So the real question is not "do we take 8.0.0?" but "are we moving the core wallet package to 12?" If you are on an earlier core version, pin to 7.0.1; taking 8.0.0 forces the core upgrade, and that upgrade — not this package — is the migration work.

Look elsewhere when:

• You are single-currency. The core package's deposit/withdraw is sufficient; a swap layer adds surface area for no user-visible benefit.
• You need external FX rate feeds, hedging, settlement with a banking partner, or regulatory-grade double-entry accounting with immutability guarantees. This is an application-level ledger, not a treasury system, and should not be pitched as one.
• You are not on Laravel/bavix/laravel-wallet — adopting this means adopting the whole wallet stack, which is a much larger decision than the swap feature warrants.

Health signal to note, not over-read: this release is mostly Dependabot and workflow bumps plus one functional change, by a small maintainer team. Active maintenance is good; low feature velocity is acceptable for a small, stable package, but it does mean your roadmap is partly coupled to the core package's release cadence.

How to Pitch It (Stakeholders)

For executives (one paragraph): we can ship currency and balance conversion — the kind of feature customers read as "the product understands my money" — by adding one small, actively maintained package rather than commissioning a conversion service and the reporting changes that go with it. Cost is a dependency plus a small amount of product design around rates and fees; time to first demo is measured in days, not a quarter. The trade-off is a version lockstep with our existing wallet library: upgrades are scheduled work, not automatic, and this 8.0.0 release is exactly that kind of upgrade rather than a feature release. The risk is contained and the alternative is a larger, permanent piece of custom code we would own forever.

For engineering (short): 8.0.0 is a compatibility release. The only functional change is support for laravel-wallet 12; the remaining entries are Dependabot bumps to CI actions and workflow config, plus moving the dev dependency phpunit/phpunit from ^10.5 to ^11.0. No new public API in the swap layer and no deprecations announced, so the adoption path is: upgrade the core wallet package first, bump this to ^8.0, run the suite, and confirm the CI runner meets PHPUnit 11's PHP baseline (8.2+). Treat "core wallet 12 migration" as the ticket; the swap package is a one-line follow-on.