Exchange Laravel Package

Product Decisions This Supports

• Multi-currency pricing and localization: Powers displaying prices, invoices, or plan costs in a customer's local currency without building and maintaining your own FX rate pipeline. Relevant for checkout localization, regional pricing pages, and localized billing.
• Market expansion roadmap: Low-cost enabler for launching in new geographies where showing local currency materially improves conversion. Reduces the "do we localize pricing?" decision to a small integration rather than a multi-sprint build.
• Build vs. buy: Strong "buy" (adopt) candidate versus building in-house. It wraps external rate providers behind a clean, driver-based abstraction, so you avoid owning provider API contracts, response parsing, and rate-object modeling. You still own caching, rounding policy, and compliance.
• Use cases to scope: E-commerce/SaaS display currency, approximate conversions, invoicing estimates, travel/fintech dashboards. It is a rate retrieval layer, not a payments/FX settlement engine—do not use it to make binding financial commitments without adding your own rounding, caching, and audit layers.
• v3.0.0 upgrade decision is low-risk and worth taking: The breaking changes are mechanical (deprecated getters removed in favor of public properties) plus a provider-side change (Frankfurter v2). The value is staying on a maintained, current provider integration; the migration cost is small for typical consumers.

When to Consider This Package

Adopt when:

• You are on Laravel/PHP and need a simple, framework-native way to fetch current exchange rates.
• Your requirements are "get a rate set for a base currency and convert/display," not historical series, hedging, or settlement.
• You want a driver-based abstraction (e.g., Frankfurter) and are comfortable owning caching, refresh cadence, and rounding rules yourself.
• You are already on 2.x and using the deprecated getters—upgrading to 3.0 is a quick, well-scoped change (swap getBaseCurrency()/getRates()/getRetrievedAt() for baseCurrency/rates/retrievedAt properties).

Look elsewhere or add significant scaffolding when:

• You self-host Frankfurter: v3 requires the v2 API and updating FRANKFURTER_BASE_URL from /v1 to /v2. Validate this in staging before upgrading.
• You need guaranteed uptime/SLA, multi-provider failover, historical rates, or rate locking for transactions.
• You require strict financial compliance, audit trails, or precise decimal handling beyond what a lightweight rate object provides.
• You are not on Laravel/PHP, or you need a managed FX service with contractual rate guarantees.

Migration notes for v3.0.0:

• Update any code calling the removed getters to the public properties.
• Confirm baseCurrency is now a float (per the changelog) and adjust type expectations/tests accordingly.
• If self-hosting Frankfurter, point FRANKFURTER_BASE_URL at /v2; note the release also introduces a frankfurter_v2 driver alongside the updated frankfurter driver—pin your driver choice explicitly.

How to Pitch It (Stakeholders)

For executives: This is a small, low-risk dependency that unblocks showing prices in local currencies—a proven conversion lever for international growth. The v3.0.0 upgrade is a maintenance release: the required code changes are minor (a few method calls become properties), and the main operational item is updating a provider endpoint if we self-host. Adopting keeps us on a maintained, current integration and avoids building and owning FX plumbing in-house.

For engineering: Clean, driver-based Laravel package for retrieving exchange rates. v3.0.0 removes the deprecated Rates getters (use baseCurrency, rates, retrievedAt properties), bumps the Frankfurter integration to v2 (self-hosters must switch FRANKFURTER_BASE_URL to /v2), adds a frankfurter_v2 driver, and normalizes base currency to float. Budget a short upgrade task: update call sites, adjust type assertions/tests, and validate the provider endpoint in staging. It deliberately does not handle caching, rounding, or historical rates—those remain our responsibility.