Currency Rates Laravel Package

Getting Started

mibo/currency-rates is a small, single-maintainer Laravel package (MIT, last tagged 2024-08-03). It is not widely adopted — zero stars and zero dependents at time of review — so treat it as a utility you evaluate before committing, not a drop-in dependency you assume is battle-tested.

Install and inspect before wiring it into anything real:

composer require mibo/currency-rates
composer show mibo/currency-rates   # check Laravel/PHP constraints, autoload, files

Then read the package source in vendor/mibo/currency-rates/ in this order:

1. composer.json — Laravel version range and whether it depends on Guzzle, illuminate/support, etc.
2. config/*.php — the base currency, default provider, API credentials, and cache TTL are almost certainly here. Publish it if a service provider registers it:

   php artisan vendor:publish --provider="Mibo\CurrencyRates\CurrencyRatesServiceProvider"
   

   (Confirm the exact provider/tag from the repo — small packages often publish under a short tag like currency-rates.)
3. src/ — look for the service class, facade, and any contract/interface. The interface is the seam you will code against.
4. README.md — the only authoritative usage example; assume it is the source of truth over any guess here.

First use case: converting a single amount for display. Something along the lines of resolving the rate service from the container and calling a convert/latest method, then formatting the result. Prove that path end-to-end against one provider before you design around it.

Implementation Patterns

Wrap it, don't sprinkle it. Because the package is unmaintained-risk, put your own ExchangeRateService interface in front of it and bind the package behind that. If the package dies or the provider changes, you swap one adapter rather than grepping the codebase.

interface ExchangeRateService {
    public function rate(string $from, string $to, ?Carbon $date = null): string;
}

Return rates as strings or integer minor units — not floats — and do rounding at the presentation edge only.

Cache aggressively, refresh on a schedule. Rates move on the order of minutes to hours, not per-request. Cache per (base, quote, date) with a TTL matched to the provider's update cadence, and refresh out-of-band:

// app/Console/Kernel.php
$schedule->call(fn () => app(ExchangeRateService::class)->refresh())->hourly();

Prefer a scheduled warm-up plus a cache read on the request path over a live API call during checkout or page render.

Persist a snapshot for anything financial. If rates affect invoices, orders, or payouts, store the exact rate and timestamp used on the row (rate, rate_at, rate_source). Never recompute historical totals from "current" rates.

Test with a fake. Bind a deterministic stub in your test suite rather than hitting the provider:

$this->app->instance(ExchangeRateService::class, new FakeRates(['USD' => '1', 'EUR' => '0.92']));

Use it for display, not accounting. Round-tripping through a third-party rate is fine for a price hint; it is not a settlement rate. Keep the two code paths separate.

Gotchas and Tips

• Vendor risk is the headline issue. One maintainer, no dependents, no recent activity signal. Pin the exact version in composer.json, vendor the lockfile, and keep the adapter boundary described above. Have a fallback provider in mind before you ship.
• Verify the provider terms. Many free FX APIs (and scrapers) forbid commercial redistribution or require attribution. Check the actual upstream source the package talks to — the package's license says nothing about the data license.
• Base-currency assumptions bite. Most rate APIs are USD-based and derive crosses by division. Cross-rate rounding error accumulates; for anything beyond two decimal display, get the direct pair or round once, late.
• Stale rates look like fresh rates. Check whether the package distinguishes "rate as of date X" from "fetched at time Y." Surface the as-of date in the UI when it matters.
• Weekends and holidays. FX markets close; a "latest" call on Sunday returns Friday's rate. Don't let a cron job interpret that as a failure, and don't let a validator reject it.
• Cache key design. Include base currency, quote currency, and date. A naive rates key will leak one tenant's base currency into another's response. If you support per-user base currencies, namespace the key.
• Failure modes. Decide up front whether a provider outage should (a) throw, (b) fall back to a cached value with a staleness flag, or (c) return null and let the UI hide the converted price. Silent fallback to 1.0 is the classic bug — never do it.
• Config quirks. Small packages often read env directly instead of via config(), which breaks under config:cache. Grep the source for env( and, if found, mirror the values into a published config file.
• Extension points. Look for an interface or a driver-style config — that is your hook for swapping providers without forking. If there isn't one, your own adapter is the extension point.
• Debugging. Log the raw provider response at debug level on failure; malformed JSON and rate-limit HTML pages are the two most common causes of a confusing exception.