Currency Laravel Package

Technical Evaluation

Architecture fit

amrshawky/currency is a framework-agnostic PHP client that wraps the public exchangerate.host HTTP API for current, historical, and crypto rates. It is not a Laravel package in the conventional sense — no service provider, no publishable config, no facade — so in a Laravel codebase it lands as a plain Composer dependency instantiated directly wherever conversion is needed. That is the core architectural concern: left unwrapped, it becomes a hard-coded outbound HTTP dependency scattered across controllers, jobs, and Blade views, with no seam for caching, mocking, or provider substitution.

The correct fit is as an infrastructure adapter behind a first-party ExchangeRateProvider interface (e.g., rate(string $base, string $quote, ?Carbon $date): Money), bound in a service provider. In that position it is perfectly serviceable. In any other position it is a liability, because the package is archived, unmaintained, and entirely dependent on a third-party free API whose commercial terms have changed since the release.

Integration feasibility

Low effort, high uncertainty. Installation is a single composer require, and the API surface is small enough to read in an afternoon. The blockers are not integration complexity but contract risk:

• Upstream API drift. The library was last released 2021-05-13 and assumes the free, keyless exchangerate.host endpoint. That upstream has since moved to an access-key model with tiering and rate limits. There is a strong likelihood the package fails out of the box with 401/403 or a changed response shape. This must be validated in a spike before any planning commitment.
• PHP/Laravel compatibility. Built for PHP 7.x/8.0-era toolchains. It will likely parse on PHP 8.2/8.3 but will emit deprecations, and its HTTP dependency constraints may conflict with Laravel's shipped Guzzle version. Composer resolution needs verification per Laravel major (9/10/11).
• No resilience primitives. Expect no timeout config, retry policy, rate-limit handling, or structured exceptions. All of that must be added in the wrapper.

Technical risk

Key questions

1. Is this for display-only conversion or for booked/accounting amounts? If the latter, what is the audit and rate-source requirement?
2. Do we have (or intend to buy) an exchangerate.host access key, or is the plan to move to a different provider entirely?
3. What refresh cadence and tolerance does the business accept — is a one-hour-old rate acceptable for a quote?
4. Are crypto rates actually in scope, or is that a package feature we will never use?
5. What is the expected request volume and pair cardinality? This determines whether per-request HTTP is viable at all.
6. Who owns this internally after adoption, given there is no upstream maintainer?

Integration Approach

Stack fit

Composer-installed PHP library; consumable from any Laravel 8+ application on PHP 8.x, subject to dependency-conflict verification. It does not participate in Laravel's container, config, or queue systems natively, so the integration work is entirely ours: a config file for base URL/key/timeouts/cache TTL, an interface, an adapter, a service-provider binding, and a facade only if the team insists on one.

Migration path

Adopt-with-a-fork, not adopt-as-is. Because the package is small and MIT-licensed, the pragmatic path is to vendor the source into our own namespace (e.g., App\Support\Fx\ExchangerateHostClient) or a private fork. That converts an unmaintainable dependency into ~a few hundred lines of owned code, removes the abandoned-upstream risk from the equation, and lets us patch the request/response handling for the current API in the same PR. Public API of the adapter stays stable, so a later swap to a maintained client or a different provider is a one-class change.

Compatibility

Pin the exact version, verify Composer resolution against the target Laravel major, run the suite on the target PHP minor and watch for deprecations, and confirm the current exchangerate.host request/response contract against a real key in a throwaway test. Do not assume 2021 behaviour still holds.

Sequencing

1. Spike (1–2 days). Call the live API with the package, with and without a key, across spot/historical/crypto. Record actual response shapes and failure codes. Go/no-go.
2. Contract first. Define the ExchangeRateProvider interface and a Money/rounding policy agreed with finance.
3. Adapter + config + binding. Vendor the client, wire it behind the interface, externalise base URL, key, timeout, and TTL.
4. Caching. Wrap in Cache::remember keyed by base/quote/date. Historical rates are immutable — cache indefinitely. Spot rates get an explicit short TTL.
5. Resilience. Timeouts, bounded retries with backoff, and a circuit breaker; fail open to last-known-good rate or closed to a handled error, decided per use case.
6. Persistence and audit. Persist fetched rates to a local table with source and fetch timestamp — required if any booked amount depends on them.
7. Tests and observability. HTTP-faked feature tests, structured logging of provider latency and error rates, alerting on error-rate threshold.
8. Rollout. Feature-flag the adapter in, shadow-compare against the current mechanism for a week, then cut over.

Operational Impact

Maintenance

Effectively 100% internal. An archived package receives no bug fixes, no dependency bumps, and no response to upstream API changes — and the upstream has already changed once. Budget ongoing ownership: a named maintainer, dependency review on each Laravel upgrade, and a scheduled quarterly check that the provider contract still holds. The vendored-fork approach makes this tractable; using it as an unmodified dependency does not.

Support

No vendor support, no active community (27 stars, single maintainer), no documented escalation path. Any incident is ours to diagnose. Mitigation is documentation: a runbook covering how to switch providers, how to purge the rate cache, and what to do when the provider returns 401/429/5xx.

Scaling

Every uncached lookup is a synchronous outbound HTTP call. On a free tier this becomes the first bottleneck — rate limits will be hit before latency becomes the problem. Scaling levers, in order: aggressive caching with correctness-aware TTLs; batch/multi-symbol queries instead of N per-pair calls; a scheduled sync job writing rates to a local table for high-volume paths so request-time conversion is a single indexed read; and queueing any non-interactive conversion work. Crypto volatility may require a shorter TTL than fiat, which argues for per-pair caching policy rather than one global TTL.

Failure modes

• Provider contract change or key enforcement → blanket 401/403; every conversion fails. Highest-probability failure given the archive date.
• Rate limiting (429) → intermittent, load-dependent failures that look like flakiness.
• Provider outage → checkout/quote flows break if conversion is synchronous and fail-closed.
• Stale cache → silently wrong prices; the most dangerous failure because it produces no error.
• Zero/malformed rate response → division or multiplication by zero/garbage, corrupting stored amounts.
• Float precision → sub-cent drift accumulating in totals; must be constrained by a documented rounding policy using integer minor units or bcmath.
• Date/timezone boundary → historical rate attributed to the wrong day, which is an audit finding, not a bug report.

Each of these needs an explicit product decision: fail-open to last-known-good (availability over accuracy) or fail-closed (accuracy over availability). That decision differs between a marketing price display and a booked receivable.

Ramp-up

Low for any PHP developer — the API is small and the mental model is a single HTTP call. Realistic estimate: 1–2 days to spike, wrap, and test the happy path; roughly one sprint-week to production-harden with caching, persistence, resilience, observability, and the provider-abstraction seam. The team should treat the ramp-up cost as small and the ownership cost as permanent.

Recommendation. Do not adopt as a standing dependency. Adopt the pattern — thin provider adapter behind an interface — and either vendor this small MIT-licensed client as owned code or go directly to a maintained provider client. The library is a reasonable reference implementation and a poor long-term dependency, and the archived status combined with a changed upstream API makes it unsuitable for anything touching money without an abstraction layer and a documented replacement path.