Laravel Swap Laravel Package

Product Decisions This Supports

• Multi-currency pricing and localized checkout. Lets you display local-currency prices, estimates, and totals without building FX plumbing — the package provides the rate layer; you own the pricing rules.
• Build vs. buy for FX. This is a strong "integrate" signal: a thin, MIT-licensed Laravel wrapper around a maintained PHP exchange-rate library. It moves "rate aggregation and provider abstraction" off your roadmap. The 2.5.0 release reinforces this — the upstream florianv/swap bump to ^4.6 pulls in Exchanger 2.11's provider fixes, so you inherit vendor maintenance rather than owning it.
• Provider and vendor-risk strategy. Multi-provider support with fallback is a product-level resilience decision, not just a technical one: you can launch on a free-tier rate source and migrate to a paid one without application changes. 2.5.0 adds UniRateAPI and the National Bank of Denmark (a free, official central-bank source), widening the set of no-cost and high-trust fallbacks available to you.
• Freshness vs. cost tradeoff. Configurable caching turns rate TTL into a lever you can tune against provider quotas, third-party cost, and latency — a decision worth explicitly owning as an SLA, not defaulting silently.
• Roadmap enablers. Geo-based currency display, subscription billing in local currency, refunds in the original currency, and reporting normalized to a single currency all become incrementally cheaper.
• Scoping guardrail. Conversion is not settlement. The package gives you rates; it does not give you payment processing, hedging, or an audited ledger of the exact rate applied to each transaction. Decide up front whether you need display accuracy or transaction-grade auditability — they imply different architectures.
• Avoids a distraction build. If requirements fit below, the right decision is to not staff a bespoke rate-cache-and-fallback service.
• Base-currency assumption is now documented, not implicit. 2.5.0's docs clarify that the exchange_rates_api free plan is EUR-based. That is a product-level detail: it changes which pairs you get directly versus which you must derive via cross-rates, and it affects rounding error on display prices. Worth deciding deliberately rather than discovering in QA.

When to Consider This Package

Adopt when:

• You're on Laravel 11, 12, or 13 and want zero-boilerplate wiring — auto-discovered service provider, facade, published config. (2.5.0 formally drops Laravel 10 and no longer tests Lumen; Lumen users are effectively frozen on 2.4.x.)
• Your need is read-oriented conversion: display pricing, geo-localized catalogs, estimates, and reporting normalization.
• Provider redundancy matters and you'd otherwise hand-roll a fallback abstraction.
• Cached, minutes-level rate freshness is acceptable for the user-facing experience.
• You want a small, easily removable dependency rather than a platform commitment.
• You want fail-fast configuration: 2.5.0 throws a clear InvalidArgumentException when swap.cache, swap.http_client, or swap.request_factory are given non-class-name values, so misconfiguration surfaces at boot rather than as a silent wrong-rate at runtime.

Look elsewhere or build when:

• You need an immutable, per-transaction rate record for accounting, tax, refunds, or dispute resolution. Store the applied rate yourself at transaction time regardless of which package you use.
• You need settlement, treasury, hedging, or contractual FX spreads — the payment provider (Stripe, Adyen, etc.) usually owns this.
• You need streaming or sub-minute rates, crypto, or thin-liquidity exotic pairs.
• Volume is high enough that per-call provider pricing or rate limits dominate; a direct paid-provider contract with your own cache may win.
• You're on Laravel 10 or Lumen and cannot upgrade — you'd be adopting a version that no longer receives fixes.
• You're outside Laravel, or you want one dependency that also covers payments.
• Your chosen rate provider's terms, licensing, or geographic restrictions are incompatible with commercial use — verify before committing, as this is the most common hidden blocker. Note for 2.5.0 specifically: the coin_layer provider transmits your API key over plain HTTP unless paid is set to true. Treat that as a security/compliance gate, not a config detail — it likely disqualifies that provider for production handling of any commercially sensitive traffic.

If you are already on 2.4.x: upgrading to 2.5.0 is a minor-version bump with a genuine breaking edge — the Laravel 10 / Lumen support drop. If you're on Laravel 11+, upgrade. Then re-publish or diff config/swap.php: 2.5.0 corrects the documented option names per provider (APILayer services use api_key, not access_key), which means anyone who worked around the old names now has a now-incorrect workaround, and anyone who copied the old config may have been running against a silently ignored key. Budget a short verification pass per configured provider rather than assuming a no-op.

How to Pitch It (Stakeholders)

Executives: This is a small, MIT-licensed integration layer that lets us price and display in local currencies in days rather than a quarter. It reduces vendor risk: it supports multiple rate providers with automatic fallback, so a degraded or expensive rate source doesn't become an outage or an emergency migration — and this release broadens that fallback pool, including to a free central-bank source. Caching keeps third-party costs and latency predictable. The surface area is deliberately thin, so if our needs outgrow it — or if we move to a provider that settles FX for us — we replace a wrapper, not our domain code. The one material caveat is platform commitment: it now requires Laravel 11+, so this is only a candidate if we're current or upgrading anyway. Low cost, low lock-in, clear exit.

Engineering: It's a thin Laravel wrapper around the maintained florianv/swap library: auto-discovered service provider, facade, and a published config file covering provider selection, fallback ordering, and cache TTL. It is not a new FX engine — it standardizes how rates, caching, and fallback are wired into the container.

Changes in 2.5.0 that affect our integration plan:

• Platform floor moves to Laravel 11/12/13. Laravel 10 and Lumen are dropped. Don't adopt on Laravel 10 expecting future patches.
• Upstream florianv/swap ^4.6 / Exchanger 2.11. Pin it and let the provider-level fixes come with it.
• Config correctness fix. Re-publish and diff config/swap.php; per-provider option names were wrong for the APILayer services (access_key vs api_key). Remove any local workaround. Add a boot-time assertion in CI that our configured provider keys resolve, so a silently ignored key can't ship.
• Fail-fast validation. Non-class-name values for swap.cache, swap.http_client, swap.request_factory now throw InvalidArgumentException. Good — wire our cache store and HTTP client by class name and let it fail loudly in CI.
• Provider docs are now test-enforced against Exchanger, which lowers the odds we code against stale documentation. Still verify current provider terms at integration time.
• Security note: coin_layer sends the API key over HTTP unless paid is true. Don't enable it without that flag and a conscious decision.
• Base-currency caveat: exchange_rates_api free plan is EUR-based — verify the pairs you actually need are direct, or accept cross-rate derivation and its rounding.

Plan to add: provider credentials in config/env, sensible cache TTLs per environment, a fake or stubbed provider for deterministic tests, and — importantly — our own persistence of the rate applied at the moment of each transaction so audit and refunds never depend on a live API call. Watch rounding and minor-unit precision explicitly, and pin the underlying library. Adoption risk is low and reversible; treat the provider relationship and rate-accuracy guarantees as the real dependency to manage.