Money Bundle Laravel Package

Technical Evaluation

Architecture fit. headsnet/money-bundle is a Symfony Bundle that wires moneyphp/money into a Symfony application — its value is largely in the DI/service wiring, form types, validators and templating helpers it layers on top of the underlying library. That is a structural mismatch with Laravel: there is no bundle/extension system, no Symfony DI container compilation pass, and no Symfony Form or Validator contracts to plug into. The genuinely portable asset is moneyphp/money itself (immutable Money objects, currency handling, parsing/formatting, allocation, rounding modes), which is framework-agnostic and PSR-compatible. For a Laravel codebase, the realistic fit is "adopt the underlying library, borrow the bundle's patterns" rather than "install the bundle."

Integration feasibility. Installing the bundle directly in Laravel would require bridging its bundle class, service definitions and any Symfony-typed constructor dependencies into Laravel's container — feasible for a small subset, but the cost is a permanent shim layer that upstream never designed for. Most of what a Laravel app actually needs (a Money cast for Eloquent, a validation rule, a Blade helper, config-driven default currency) is straightforward to build locally against moneyphp/money in a day or two. Integration feasibility of the bundle as intended in Laravel is low; of the domain capability, high.

Technical risk. Three items stand out. First, versioning posture: this is a 0.x package, so the minor bump from 0.1.12 to 0.2.0 carries a breaking change — the minimum PHP version is raised to 8.1. Any environment on PHP 8.0 (Laravel 9 still permits 8.0) is cut off and must pin to 0.1.x. That is semver-legal pre-1.0 but means upgrade boundaries are not signalled by the version number. Second, bus factor: the project is maintained by a small group (headsnet, with this release authored by a single contributor), so long-term support depth is limited and should be assumed accordingly. Third, opacity: the release notes contain exactly one line, with no CI matrix detail, no mention of deprecation fixes for the newly supported 8.4 target, and no security review — so "supports 8.4" is a claim to verify in our own pipeline rather than a guarantee.

Key questions.

• Is our lowest-supported PHP runtime ≥ 8.1 across all environments (app, queue workers, CI, local Docker images)? If any leg is 8.0, we cannot take 0.2.0.
• Do we actually need the Symfony-layer features, or only moneyphp/money? If the latter, does adopting the bundle add value at all?
• Does the bundle pin moneyphp/money to a version range that conflicts with what our other dependencies require?
• What is the maintenance commitment behind this repo — release cadence over the last 12 months, open-issue responsiveness, security policy?
• Is there a Laravel-native alternative (or a trivial in-house wrapper) that gives equivalent behaviour without a cross-framework shim?

Integration Approach

Stack fit. Target stack should be Laravel 10+ / PHP 8.1–8.4, which aligns cleanly with the new floor. Composer constraint should be headsnet/money-bundle: ^0.2 only if we decide to consume the bundle; otherwise depend on moneyphp/money directly with its own caret constraint and skip the bundle entirely. Recommendation: treat moneyphp/money as the dependency of record and treat this bundle as a reference implementation we read, not ship — unless a concrete feature in the bundle is demonstrably cheaper to bridge than to rebuild.

Migration path. For any environment still on PHP 8.0, pin to 0.1.12 and treat that as a hard ceiling; the upgrade to 0.2.0 is gated on the PHP runtime bump, not on API changes. Sequence: (1) inventory PHP versions across app, workers, CI runners and container base images; (2) raise any stragglers to 8.1+; (3) bump the constraint; (4) run the full test suite plus a manual pass over any money-handling paths, since a PHP minor bump can surface implicit-nullable and deprecation notices in transitive code. Where we are consuming only moneyphp/money, this release is effectively a no-op for us and we should record it as such rather than schedule work.

Compatibility. Verify moneyphp/money, brick/math (or whichever math backend is in use) and any intl extension requirements resolve cleanly under PHP 8.4 before claiming 8.4 readiness. Confirm the bundle's own dependency ranges are not pinned to stale Symfony majors that would block co-installation with our other packages. If we run the bridge shim, that shim needs its own compatibility matrix against the bundle's internal service names — those are not part of a stable public API at 0.x and can move in any minor release.

Sequencing. Low priority. There is no functional gain here — no new capability, no deprecation work required of us. Schedule it behind feature work, bundle it with a routine dependency-refresh cycle, and only escalate if the PHP 8.4 support is a prerequisite for our own 8.4 migration timeline.

Operational Impact

Maintenance. Expect to own the integration glue ourselves. Every bundle minor version may move internal service definitions, and at 0.x there is no compatibility promise protecting a custom Laravel bridge — so the shim becomes a recurring tax on every upgrade. Consuming moneyphp/money directly inverts this: the maintenance surface is a thin set of app-local value-object casts and validation rules that we control and can change without upstream coordination. Ongoing cost is roughly one dependency review per quarter plus a security watch on the underlying money library, which is the component with the real risk profile (currency data, rounding, parsing).

Support. No commercial backing and no published support SLA. Upstream responsiveness is a single-maintainer-effort proposition; budget for the possibility that a critical fix lands slowly and be prepared to vendor a patch or fork for the money library. Internal support burden falls on whichever team owns the payments/pricing domain — that team should hold the expertise, not a platform team, because the failure modes are domain failures rather than infrastructure failures.

Scaling. Negligible runtime scaling impact. Money objects are created per-operation and are cheap; the bundle introduces no I/O, no caching layer, no async surface. The one thing that does scale is the number of code paths touching monetary values — the more pervasive the money type, the more important a consistent, enforced representation (integer minor units vs. decimal strings) becomes. Whatever wrapper we choose should make the storage format impossible to bypass.

Failure modes. The expensive failure here is silent monetary corruption, not downtime: incorrect rounding on allocation/splitting, mixed-currency arithmetic slipping through without an exception, locale-dependent parsing producing off-by-100 errors, or a DB column with insufficient precision truncating decimals. Secondary failure mode is dependency-resolution deadlock — a pinned transitive constraint blocking an unrelated security patch, which is a realistic outcome when a 0.x bundle pins Symfony components. Tertiary is the PHP-version cliff: a forgotten 8.0 container in a CI leg or an async worker image causes production/runtime divergence that only manifests on deploy. Mitigations: a single canonical money cast/accessor with no raw-float escape hatch, explicit currency pairing at the type level, round-trip tests against stored values, and a CI matrix that runs the actual PHP versions present in every deployment target.

Ramp-up. Low for engineers already fluent in Laravel's container and Eloquent casts — the underlying moneyphp/money API is small and well-documented (a handful of methods: add, subtract, multiply, allocate, format). A day of pairing plus the canonical cast implementation is sufficient onboarding. The higher ramp-up cost is domain education: getting the team aligned on minor-unit storage, rounding policy and currency boundaries is where the real lead time sits, and it is independent of whether this bundle is in the dependency graph.