Laravel Revaluation Laravel Package

Technical Evaluation

Architecture fit. The package follows the classic Laravel 5.x package shape: a service provider, a facade alias, a publishable config file for currency definitions, a rate-provider abstraction, and a cache decorator around provider lookups. That decomposition is the right one for a multi-currency feature — a RateProvider contract, a cached repository, and a thin converter service — and it maps cleanly onto a domain module in a modern Laravel app. The problem is the implementation era, not the design: the code targets PHP 7.0 / Laravel 5.5–5.8 idioms (no scalar/return types, likely use of helpers removed in Laravel 6+, illuminate/support constraints pinned to old majors, facade registration via config/app.php rather than package discovery conventions we may rely on).

Integration feasibility. As a composer require dependency: low. Archived since 2018-03-28, 30 stars, no upstream patches. On Laravel 9+/PHP 8.2 you will either fail platform constraints or be forced into --ignore-platform-reqs, which is an unacceptable production posture. As a reference implementation and specification: high. The provider contract plus cache wrapper is perhaps a few hundred lines; copying and re-homing it into our own Currency module costs a day or two and eliminates the dependency.

Technical risk.

• Financial correctness is the dominant risk, and it is under-specified. Unclear whether amounts are floats or integer minor units; unclear rounding policy (half-up vs banker's vs NumberFormatter); unclear handling of negative amounts (credits/refunds), zero-decimal currencies (JPY), and three-decimal currencies (BHD, KWD).
• Rate semantics: does it store only the latest rate, or historical rates? Invoicing and reporting require a snapshot rate at transaction time — read-time conversion is a latent bug.
• Pair coverage: no evidence of cross-rate triangulation when a direct pair is missing, or inverse-rate derivation.
• Provider staleness: bundled rate sources likely point at endpoints/APIs that have changed or died since 2018.
• No security or CVE feed for a package that parses third-party HTTP responses and writes to cache.

Key questions for the spike.

1. Which Laravel and PHP versions does the constraint set actually permit, and does it run green on a scratch app on our current stack?
2. Float or minor-unit arithmetic? Where is rounding applied, and can we inject our own rounding policy?
3. Does the provider contract expose as-of date queries, or only "latest"?
4. Is cache TTL configurable, and is there stampede protection / negative caching on provider failure?
5. What happens on provider outage or unknown pair — exception, null, or silent fallback to 1.0? (Silent fallback would be a release blocker.)
6. Can we snapshot rates into our own persistence without forking?

Integration Approach

Stack fit. Only a fit if we are on Laravel 5.x / PHP 7.x. On anything modern, treat this repository as a design input, not a runtime dependency. Its README and config file are effectively a free requirements checklist for the feature.

Migration path. Three viable options, in order of preference:

1. Reference extraction (recommended). Vendor the concepts — RateProvider interface, CachedRateProvider decorator, CurrencyConverter service — into app/Domain/Currency with our own types, brick/money (or moneyphp/money) for arithmetic, and our treasury/ECB/vendor feed behind the provider contract.
2. Internal fork. Only if the existing code is genuinely closer to done than a rewrite — unlikely at this size. Fork → rename namespace → add PHP 8 types → add illuminate/support ^10||^11 → add tests → publish internally. Carries permanent ownership cost.
3. Adopt as-is. Not recommended under any timeframe we would defend in a review.

Compatibility checks before deciding. Run composer why-not against the target app; grep the source for removed helpers (array_get, str_*, camel_case); confirm the facade alias and config-publish tags do not collide with existing config keys; confirm how it resolves the HTTP client (Guzzle major version conflicts are the usual killer).

Sequencing.

1. Day 1–2: decision spike. Read the source end to end, run it in a throwaway Laravel app on our version, tabulate the key questions above. Output: adopt / extract / replace.
2. Day 3–5: contract design. Define our RateProvider, RateRepository (with persistence for historical snapshots), and rounding policy. Borrow the package's interface shape where it is sound.
3. Week 2: rate sourcing. Implement the concrete provider against our chosen feed, with TTL cache, negative caching, timeout/retry, and a persisted daily-rate table.
4. Week 2–3: domain wiring. Pricing, invoices, and multi-currency reporting consume the module; conversion happens at transaction time with the rate stored alongside the money value.
5. Week 3: shadow mode. Run alongside the current process, diff outputs against known-good invoices and FX rates before cutover.

TPM leverage. Frame this as "we found a prior-art implementation that de-risks the contract design and costs us two days to evaluate." That is a cheap, defensible win regardless of the adopt/replace outcome — and it prevents a team from gold-plating a rate-provider abstraction from scratch.

Operational Impact

Maintenance. Archived means zero upstream: no bug fixes, no PHP-version bumps, no security patches, no response to issues. Every line becomes ours the moment we depend on it. If we adopt as-is, assign a named owner and a calendar reminder to review at each Laravel major upgrade; if we extract, the maintenance surface is limited to our own module and is straightforward.

Support. No community to escalate to (30 stars, no maintainer activity since 2018). Internal support only, which means the on-call runbook must be written by us — including what to do when a rate feed returns garbage or nothing.

Scaling. Conversion math is trivially cheap; the actual scaling concerns are (a) cache hit ratio and stampede behavior on TTL expiry, (b) provider rate limits and cost per call, and (c) reporting queries over historical rates — which need a persisted rate table and an index on (base, quote, as_of_date), not a live API call per row. None of these are solved by the package's cache layer alone.

Failure modes to design for explicitly.

• Provider outage — must fail closed for checkout (block with a clear error) rather than silently converting at a stale or default rate.
• Stale TTL — rates cached past a policy threshold should be flagged, not used silently for invoices.
• Unknown pair — decide up front: cross-rate triangulation, or a hard error. Silent 1.0 fallback is a financial incident.
• Rounding drift — cent-level discrepancies that surface as reconciliation breaks weeks later; requires a single rounding policy applied at the boundary, tested with property-based cases.
• Cache key collisions — pair normalization (case, whitespace, USD vs usd) must be enforced centrally.
• Config drift — currency definitions living in a published config file drift from the ledger's chart of accounts; source of truth should be the database or finance-owned config, not a package config.

Ramp-up. The codebase is small enough that a mid-level engineer can read it in an afternoon; the package is not the learning curve. The real ramp-up is domain fluency — minor units, rounding conventions, rate snapshotting at transaction time, and the difference between "current rate for display" and "booked rate for the ledger." Budget onboarding around a short written policy doc (rate sourcing, rounding, failure handling) rather than around this repository, and treat the package as the worked example that doc references.