Swap Bundle Laravel Package

Technical Evaluation

Architecture fit. Unchanged. part-db/swap-bundle remains a Symfony bundle — the DI/config integration layer around the framework-agnostic florianv/swap currency-exchange library — and its core artifacts (Bundle class, DependencyInjection/Configuration.php, service XML/YAML) are still inert inside a Laravel kernel. In a Laravel application only the underlying florianv/swap library transfers. v6.2.0 does not alter this; it is a version-alignment release, not an architectural one.

What v6.2.0 actually changes. The release body is a single line — "Updated to upstream version v6.0" — plus a GitHub compare link. Read literally, this means the fork has rebased onto upstream florianv/swap-bundle v6.0. Three implications matter more than the diff size suggests:

1. The fork is tracking upstream, not drifting. This is the first real evidence bearing on our open question #8 ("why does this fork exist / is it tracking upstream tags?"). A major-version rebase is a maintenance commitment, and it partially retires the divergence concern. It does not retire the bus-factor concern.
2. A major upstream bump implies a platform floor change. Upstream bundle v6.0 is conventionally a Symfony 6/7 + PHP 8.1/8.2-era line, with Symfony 5.4 support dropped. If that holds here, v6.2.0 is a breaking change for anyone on Symfony 5.4 or older PHP, and consumers must pin to 6.1.x to stay supported. This must be verified against composer.json, not inferred from the tag name.
3. The release notes are non-substantive. "Updated to upstream v6.0" with no changelog, no breaking-change statement, no migration notes, and no CI status. For a financial-correctness dependency, a major rebase described in one sentence is itself a review finding — the burden of diffing v6.1.0...v6.2.0 and the upstream v5→v6 upgrade guide falls entirely on us.

Integration feasibility. Unchanged for Laravel. Effort estimates hold:

Technical risk. Updated from the prior assessment:

• Adoption risk (high, unchanged): still no observable downstream usage. A single release does not create a dependent ecosystem, and there is no field evidence the post-rebase config surface is exercised outside Part-DB's own deployment.
• Governance risk (high, marginally improved): single-organization fork, bus factor of one team. The v6.0 rebase is a positive maintenance signal — the maintainers are willing to do major-version work — but it also demonstrates that the fork will inherit upstream's breaking changes on upstream's schedule, with the fork's own release discipline layered on top.
• Version-alignment risk (new, medium-high): a major upstream rebase is the highest-risk class of change for a config-layer package. Symfony bundle majors routinely rename config keys, drop provider integrations, change default HTTP clients, and remove deprecated service aliases. None of that is documented in the release notes. Anyone upgrading from 6.1.0 must assume breakage until proven otherwise.
• Release-signal risk (medium, unchanged): the previously flagged 2026-08-23 forward-dated tag remains unexplained, and v6.2.0 arrives with no accompanying correction or release-process note. Still requires manual verification of tag provenance, signed commits, and CI status before pinning.
• Financial-correctness risk (medium, unchanged): rounding policy, decimal precision, and rate provenance are still not owned by this package. A version rebase is exactly the kind of change that can silently alter default provider selection or rate-fetch semantics — which is why correctness must be pinned by our own tests, not by the dependency's version.

Key questions for the maintainer/vendor. Revised — #2, #3, and #8 are now partially answerable from v6.2.0 but not resolved:

1. Which rate providers are supported, and which are exercised in CI? Did the v6.0 rebase drop any provider?
2. New: What is the precise platform matrix for v6.2.0 (PHP floor, Symfony 5.4/6.x/7.x support)? Is 6.1.x still maintained for Symfony 5.4 users, and for how long?
3. New: What breaking changes does the v6.0 upstream rebase bring — config key renames, removed services, changed defaults, altered cache/HTTP-client contracts? Is there a migration note beyond the compare link?
4. New: Is there a tagged changelog or release-note policy? "Updated to upstream v6.0" is not sufficient for a financial dependency.
5. Is the 2026-08-23 tag intentional? What is the release process and backport policy?
6. Does it support historical rates and rate persistence, or spot rates only? Did v6.0 change this?
7. What caching abstractions are assumed (PSR-6/PSR-16, Symfony Cache contracts)?
8. Are provider API keys handled via config only, with no credential logging?
9. Is any rounding/decimal-precision policy baked in, or fully delegated?
10. Reframed: with the fork now tracking upstream majors, what is the stated lag between an upstream release and the fork's rebase — and does the fork carry any patches on top of upstream v6.0, or is it a pure mirror?

Integration Approach

Stack fit. Unchanged: poor as-shipped, acceptable as a pattern. The capability (fetch, cache, convert) is stack-agnostic and fits a Laravel service layer cleanly; the Symfony wrapper does not. v6.2.0 reinforces the recommendation — a package that rebases onto upstream majors and documents the change in one line is a package you want to consume at the library layer, where you control the pinned version and the migration timing.

Migration path (Laravel). Unchanged, and now more clearly correct:

1. composer require florianv/swap directly — skip the bundle. Check which florianv/swap major the bundle's v6.2.0 rebase targets, and pin that same major in our own constraint so our adapter and the bundle's assumptions stay legible to each other.
2. Author CurrencyExchangeServiceProvider registering a singleton Swap builder from config/currency.php.
3. Bind a CurrencyConverter contract (convert(Money $amount, string $to, ?DateTimeInterface $at): Money).
4. Cache decorator over Laravel's cache repository; TTL aligned to provider refresh cadence (6–12h defensible for ECB's business-daily publication).
5. Expose via facade or inject into pricing/BOM services; never call providers inline in request handlers.

Migration path (Symfony, if that is actually the target). Register in config/bundles.php, publish config, set credentials via env, pin to a verified tag — and now, explicitly test the v6.0 rebase before adopting: config-key compatibility, service alias availability, and any changed provider defaults. Treat 6.1.0 as the known-good fallback until 6.2.0 is verified in a scratch app.

Compatibility. Re-verify, with new emphasis:

• composer.json PHP constraint for v6.2.0 vs. our runtime — the v6.0 rebase likely raised the floor.
• Symfony range for v6.2.0, and whether 5.4 is still in it. If not, and we have any Symfony 5.4 surface, stay on 6.1.x deliberately and document why.
• Whether florianv/swap itself moved a major alongside the bundle rebase, and whether its HTTP client conflicts with Guzzle versions pinned elsewhere.
• Run composer why-not part-db/swap-bundle 6.2.0 and composer why-not florianv/swap <target> before committing.

Sequencing. Prior plan with one inserted step:

1. Spike (1 day): confirm platform; verify tag provenance and CI status for v6.2.0; run a live conversion in a scratch app.
2. Rebase diff review (0.5–1 day) — new: read v6.1.0...v6.2.0 and the upstream v5→v6 upgrade guide. Enumerate breaking changes. Decide adopt / hold at 6.1.x / abandon.
3. Adapter (2–3 days): provider, config, contract, cache layer, unit tests with recorded HTTP fixtures.
4. Correctness (2 days): rounding policy, decimal handling, currency allowlist.
5. Resilience (2 days): fallback provider, cached-static-on-failure, circuit breaker, alerting.
6. Rollout: internal pricing first, then customer-facing.

Total remains ~1.5–2 engineer-weeks for a Laravel integration — the added diff-review step is half a day, but it is only required if we adopt the bundle, which we should not.

Operational Impact

Maintenance. The bundle is an operational liability in direct proportion to how much of it we use — and v6.2.0 sharpens the point. A fork that tracks upstream majors means our upgrade treadmill is now coupled to upstream's release cadence plus the fork maintainer's rebase lag, with neither documented. Adopting the bundle in a Laravel codebase means owning a permanent incompatibility plus that coupled treadmill; adopting the core library means owning ~200 lines of glue and a version pin we choose. Prefer the latter. Track florianv/swap releases directly and pin exactly; do not float a financial dependency.

Support. Effectively none, unchanged. No dependents, no visible issue traffic, no community, no vendor escalation path. v6.2.0's single-line release note is a concrete illustration of the support posture: major-version information is not curated for consumers. Internal ownership must be assigned explicitly — named team, documented on-call path — and the fork escape hatch priced in from day one.

Scaling. Unchanged; provider quotas remain the binding constraint, not application throughput.

• Provider quotas: free tiers impose request caps and often no SLA. Cache aggressively; precompute rate tables at volume.
• Cache fan-out: shared store (Redis), not per-node file cache, or replicas disagree on rates within a single session.
• Batch workloads (BOM pricing, catalog revaluation) consume a snapshot table, not the live library.
• New: an upgrade to v6.2.0 that changes default provider selection or cache semantics would invalidate warm cache entries and rate-table snapshots. Budget a cache-flush and re-warm step into any version bump of a financial dependency.

Failure modes and mitigations.

Ramp-up. Integration ramp-up stays low — a mid-level engineer wires the core library in a day. Operational ramp-up remains the real cost: rate provenance, refresh cadence, cache semantics, monetary rounding. Add one item to the runbook in light of v6.2.0 — "a dependency upgrade changed our rates" — covering how to detect it (golden-value conversion tests against a fixed set of pairs and a recorded fixture), how to confirm which version is deployed, and how to roll back. Budget a short internal design note plus the runbook.

Verdict. Do not adopt part-db/swap-bundle for a Laravel/PHP stack. v6.2.0 is a mild positive signal — the fork is rebasing onto upstream majors rather than drifting, which answers part of our open governance question — but it is delivered as a one-line note over an undocumented major-version bump, with the forward-dated tag still unexplained and no dependent ecosystem to validate the result. For Laravel, consume florianv/swap directly behind a first-party adapter. For Symfony, treat v6.2.0 as unverified until the rebase diff and platform matrix are confirmed, and hold at 6.1.0 in the meantime. The capability is worth having; this package is still not the reason.