Openexchangerates Laravel Package

Getting Started

1. Install and configure credentials. composer require qbil-software/openexchangerates, then register a free App ID at openexchangerates.org and place it in .env (e.g. OPENEXCHANGERATES_APP_ID=). Never hard-code it — the free tier is rate-limited per key, and leaked keys get throttled or revoked.
2. Publish/inspect the config first. Check whether the package ships a config file (php artisan vendor:publish --provider=...) or reads env directly. This is a 2021-era, single-purpose wrapper, so expect a thin config array (app id, base currency, maybe a timeout) rather than a rich Laravel integration.
3. Read src/ before the README. With 2 stars and no dependents, the source is short and is the real documentation. Look for the client class, how it issues HTTP calls (Guzzle? cURL? file_get_contents?), and how it returns data (raw array vs. a DTO). Confirm the exact method names — don't assume from the README.
4. First use case: convert a stored USD price into the visitor's display currency for a product page. Pull latest rates once, cache them, and do the multiplication yourself. That's 90% of real-world usage of a package like this.

Before you commit, run composer why-not / check composer.json for PHP and Guzzle constraints — a 2021 package may pin Guzzle 6/7 or cap PHP at ^7.4|^8.0, which can fight a modern Laravel 11 app.

Implementation Patterns

Wrap it, don't sprinkle it. Bind the client behind your own interface so the package is replaceable:

interface FxRateProvider {
    public function rates(string $base = 'USD'): array;
    public function rate(string $from, string $to): float;
}

Resolve the package client inside a single adapter class registered in a service provider. When this package inevitably goes unmaintained (or you outgrow the free tier), you swap the adapter for Laravel's Http::get('https://openexchangerates.org/api/latest.json', ...) in ~15 lines.

Cache aggressively; the API updates hourly. Never call the API per request. A Cache::remember('fx.rates.usd', now()->addHour(), ...) wrapper is the difference between a 40 ms page and a 400 ms page, and keeps you inside the free tier's ~1,000 requests/month. Better: a scheduled fx:warm-rates command that fetches once and writes to cache and a fx_rates table, so you have history when you need it.

Store the rate with the transaction. For orders, invoices, and payouts, persist the rate you used on the record (orders.fx_rate, orders.base_currency). Recomputing from "today's rate" on an old order is a classic support-ticket generator.

Cross-rate conversion. Most free tiers only serve USD-based rates. Convert via USD: amount * (rate[to] / rate[from]). Put this in one helper — Money::convert() — and never repeat the arithmetic inline.

Testing. Fake the provider interface in feature tests ($this->instance(FxRateProvider::class, new FakeFxRateProvider())). Don't let unit tests touch the network; if the adapter uses Guzzle directly, Http::fake() won't intercept it, so the interface binding is your only clean seam.

Gotchas and Tips

• Audit before you depend on it. Last release 2021-05, 2 stars, 0 dependents. That is not a red flag for a 100-line HTTP wrapper, but it does mean no security patches, no PHP 8.3/8.4 testing, and no upstream fixes. Read the source in full — it's small enough — and be prepared to vendor/fork it.
• Free-tier constraints are the real product decision. USD-only base, monthly request cap, and historical endpoints behind a paid plan. If you need EUR-base or time-series, this package can't conjure it; you're buying a plan.
• Failure must not break checkout. Wrap every call in try/catch with a fallback to the last cached rate, and log the failure. A 503 from the FX API should degrade prices, not 500 the product page.
• Float precision and rounding. Rates arrive as floats. Convert in the largest unit, then round explicitly to the target currency's minor-unit count (JPY has 0, most have 2, some have 3). Don't round twice — round once, at display.
• Check the error surface. Most thin clients either throw a generic exception or return null/false on a bad key. Inspect what happens with an invalid App ID and a malformed response, and normalize it into your own exception type so callers have one thing to catch.
• Debugging checklist: (1) is the env var actually loaded — config('...') after php artisan config:clear; (2) does the raw response contain a {"error": true, "status": 401} body, which many clients silently pass through; (3) is the cache masking a working call with stale data — test with the cache store set to array.
• Extension points are thin by design. The realistic extensibility is: swap the underlying HTTP client, swap the cache, swap the whole provider. Don't expect hooks, events, or a driver system.
• Version-pin it. "qbil-software/openexchangerates": "1.0.*" rather than ^1.0, and add a calendar reminder to revisit — for a package this size, the honest long-term plan is to inline the two HTTP calls yourself.