Swap Bundle Laravel Package

Product Decisions This Supports

• Build vs. buy for FX conversion. This package answers a recurring roadmap question: do we stand up our own rate-fetching, normalization, fallback and caching layer, or adopt one? It is a thin Symfony bundle over the mature florianv/swap library, so the real decision is "adopt the library + ~a day of wiring" versus "own a small internal FX service." For indicative/display pricing, that's an easy buy.
• Stack-fit caveat that changes the decision. Despite being filed alongside Laravel/PHP packages, this is a Symfony bundle, not a Laravel package. In a Laravel codebase the correct move is to depend on florianv/swap directly and write a small service provider — same capability, one less opinionated layer. Treat this repo as the reference implementation and the library as the dependency.
• Platform floor is now a gating criterion. Release 6.0.0 requires PHP ^8.2 and Symfony ^6.4 | ^7.0 | ^8.0. That aligns cleanly with Laravel 11/12 (PHP 8.2+) and current Symfony LTS lines, so it is not a blocker for a modern codebase — but it does rule out older services and should be checked against your fleet's PHP baseline before it enters a roadmap.
• Multi-currency display and localization scope. Decides whether "show prices in the user's currency" ships this quarter or next: configurable services and provider abstraction mean the feature is configuration plus a view layer, not new infrastructure.
• Provider strategy as an availability/SLA decision. The fallback chain is the product decision, not an implementation detail. Which providers, in what order, defines your uptime and your worst-case staleness — surface it in the PRD rather than leaving it to a config file.
• Caching TTL as a freshness-vs-cost tradeoff. Rate limits and provider costs are real; TTL is the dial. This package makes that dial explicit, which lets you choose a defensible policy (e.g., hourly refresh with a "rates are indicative" disclaimer) instead of discovering it after a provider bill.
• Scope boundary: indicative vs. transacted. The package converts numbers; it does not settle, ledger, or hedge. Deciding that checkout conversion is display-only and settlement stays in a single base currency is a product and finance decision this tooling supports cleanly — and one it cannot support if you drift into contractual rates.
• Vendor-risk isolation. Swapping providers is a config change, which de-risks any single FX vendor's pricing or deprecation announcement.

When to Consider This Package

• You are on Symfony 6.4+ / 7 / 8 and want FX as a configured service rather than a bespoke integration. This is close to a drop-in, and 6.0.0 explicitly added Symfony 8 support so the forward path is clear.
• You need more than one rate source, or uptime matters. The fallback + caching combination is the whole value proposition; a single-provider, best-effort need does not justify the dependency.
• Display, indicative pricing, or reporting conversions at modest volume — cart estimates, localized catalogues, internal dashboards.
• You want the abstraction, not the integration work. If your team would otherwise spend a sprint on retries, normalization and cache keys, adopt.
• Look elsewhere or build thin glue if:
  • You are on Laravel — use florianv/swap directly; this bundle adds Symfony-only surface area.
  • You are on PHP < 8.2 or Symfony < 6.4 — 6.0.0 is a hard break with no compatibility shim; staying on 5.5.x means an unmaintained line.
  • You need tradable, contractual, or settled rates, a multi-currency ledger, or FX licensing/regulatory coverage (PSD2, KYC, hedging). This is not that product.
  • You need high-frequency conversion on a hot path — a per-request cache-backed call is not a substitute for a local rate table or in-process cache.
  • You need deep historical time-series at scale for analytics or backtesting.
  • Adoption signals matter to your org. 63 stars, 0 dependents, and a low opportunity score (31.38) against a high composite score still indicate a niche, low-visibility package. What 6.0.0 changes is maintenance hygiene, not popularity: a modernized CI matrix (PHP 8.2–8.5), PHPUnit 11/12, Psalm level 1 static analysis, and a backward-compatibility check workflow. Pin versions, run a short spike, and wrap the integration so the exit stays cheap.

How to Pitch It (Stakeholders)

To executives: Currency conversion is a commodity capability — we should not build or staff it. This is a small, MIT-licensed integration that gives us multi-provider rates with automatic failover and caching, turning a multi-week infrastructure item into roughly a day of configuration. It also removes single-vendor risk, since switching providers is a config change rather than a rewrite. The tradeoff is honest: it is a small, low-adoption open-source project, so we pin versions and keep the integration thin enough to replace. The recent 6.0.0 release is a good signal — the maintainer modernized the toolchain (current PHP/Symfony support, static analysis in CI, automated backward-compatibility checks) rather than letting it drift. The catch is that it is a breaking release: it requires PHP 8.2+ and Symfony 6.4+, which fits our stack but means no support for older services.

To engineering: The bundle is a configuration and DI layer over florianv/swap; the real dependency is the library. That means low lock-in and a clean exit — we depend on an interface, not an implementation. Two things to plan for: it is Symfony-only (on Laravel we take the library and write our own service provider), and with 0 dependents we should still spike it and pin the version. 6.0.0 removed a lot of legacy baggage — PHP <8.2, Symfony <6.4, PHPUnit 5–9, the Guzzle 6 adapter (now php-http/guzzle7-adapter), and the old Travis config — so upgrading is a floor bump, not a feature change; budget for dependency alignment and re-running the test suite. Wrap it behind our own CurrencyConverter contract so a future swap-out is a one-file change. Caching TTL and the provider fallback order should be reviewed as product decisions, not left as default config.