Laravel Money Laravel Package

Technical Evaluation

TPM take: Adopt conditionally for Laravel applications that need safer monetary value handling, but treat elegantly/laravel-money as an internal implementation detail rather than a platform-level commitment. The package is a thin, focused Laravel adapter over brick/money; the underlying money model is strong, while the adapter itself has low external validation (19 stars, 0 dependents). Leverage it behind an internal abstraction and pin versions.

Architecture fit: Good fit for Laravel-centric products with invoices, payments, subscriptions, wallets, or pricing logic. It supports Eloquent casts to Brick\Money\Money, parsing from strings/ints/floats, and validation through ValidMoney. It fits multi-currency designs when models store both a minor-unit integer amount and an ISO currency column, and it supports fixed currencies per field. It is not a full money platform: it does not provide FX conversion, tax calculation, ledgering, accounting reconciliation, or advanced formatting. TPM should scope it as a domain primitive for storing and validating monetary values, not as a complete billing or finance subsystem.

Integration feasibility: High for greenfield Laravel work. Developers can define bigInteger amount columns plus string(3) currency columns, add MoneyCast::of('currency'), and use ValidMoney in Form Requests or Livewire. Moderate for legacy systems because existing decimal/float schemas need audit, backfill, dual-write/read considerations, and API contract review. The v2 serialization change—returning floats instead of strings—is a concrete integration risk for APIs, exports, and downstream consumers.

Technical risk: Low direct implementation risk because the package delegates money arithmetic to a mature library and the feature surface is small. Medium governance risk because the adapter has limited adoption, a small maintainer/community footprint, and a history of breaking namespace and serialization changes between major versions. Risk increases if teams expose Money objects directly in APIs, rely on implicit float serialization, or mix monetary libraries. Database migration from floats/decimals to minor-unit integers is the largest delivery risk.

Key questions:

1. Which domains adopt this first: invoicing, checkout, subscriptions, or internal reporting?
2. Is multi-currency required, and are currencies fixed per model or stored per row?
3. What is the canonical API representation: minor-unit integer plus currency, decimal string, or formatted string?
4. How will legacy monetary columns be migrated without precision loss, and what reconciliation proves correctness?
5. Which currencies and edge cases must be covered: negative amounts, zero-decimal currencies such as JPY, rounding modes, and min/max validation?
6. Will the team wrap the package behind an internal Money service/factory to limit upgrade and replacement cost?
7. What Laravel/PHP version matrix must be supported, and who owns dependency upgrades?
8. Is there a support expectation beyond community GitHub issues, and can the team fork under MIT if needed?

Integration Approach

Stack fit: Strong for Laravel applications using Eloquent, Form Requests, Livewire, queues, and standard validation pipelines. It aligns with brick/money and common database designs using bigInteger minor units plus ISO currency codes. API layers should not expose the cast object directly; use API Resources to define explicit output using integer minor units plus currency, or a documented decimal string contract. Reporting and analytics should aggregate minor-unit integers in SQL and only convert at the presentation boundary.

Migration path: Start with an inventory of all monetary fields and their units. Classify fields as new, legacy, fixed-currency, or multi-currency. For greenfield tables, use bigInteger amount plus string(3) currency and adopt MoneyCast immediately. For legacy tables, add parallel columns, backfill with a documented rounding policy, reconcile old versus new values, then switch reads and writes behind feature flags. Introduce ValidMoney at input boundaries before broad cast adoption so malformed inputs fail early. Preserve old API fields during a deprecation window if clients expect floats or strings.

Compatibility: The package advertises Laravel 10–12 support through recent releases, and brick/money is the key transitive dependency. Verify the exact PHP/Laravel matrix in composer.json before commitment. Pin the major version, test upgrades in CI, and monitor both adapter and brick/money releases. The v2 namespace change from Finller\Money to Elegantly\Money and the serialization change to floats are reminders that major upgrades need contract tests. Avoid mixing this package with other money abstractions in the same bounded context.

Sequencing:

1. Run a short technical spike and record an ADR covering schema, API serialization, rounding, and ownership.
2. Build an internal adapter/service around MoneyParser, MoneyCast, and ValidMoney so product code depends on local interfaces.
3. Pilot on one bounded context, ideally invoices or checkout, with new tables or isolated fields.
4. Add validation rules and contract tests for nulls, empty strings, negatives, zero-decimal currencies, min/max boundaries, and rounding.
5. Migrate legacy data with backfill scripts, reconciliation reports, and rollback plans.
6. Update API Resources and client documentation before changing serialized outputs.
7. Expand adoption only after the pilot demonstrates precision, performance, and operational stability.

Operational Impact

Maintenance: Low code-maintenance burden because the package is a small adapter, but low adoption means the team must own upgrade discipline. Pin versions, automate dependency updates, run static analysis and tests, and keep a fork/escape plan given the MIT license. Assign an internal owner for monetary domain decisions, not just package upgrades.

Support: Expect community-style support through GitHub rather than a commercial SLA. Internal runbooks should cover schema conventions, parse/cast behavior, validation boundaries, and API serialization rules. Developer ramp-up is low for Laravel developers using casts and validation, but medium for teams new to value objects, minor-unit storage, and multi-currency correctness.

Scaling: Runtime overhead is likely modest relative to database and network costs. bigInteger storage is efficient and avoids floating-point arithmetic in application code. Watch bulk imports, exports, reporting queries, and serialization paths; these are more likely to create scale issues than the cast itself. Multi-currency reporting still requires an FX strategy outside this package.

Failure modes: The highest-risk failures are unit mismatches during migration, missing or invalid currency values, API clients misinterpreting float serialization, inconsistent rounding between input, storage, and display, and incorrect handling of zero-decimal currencies or negative amounts. Validation min/max mistakes and nullable/empty-string parsing differences can also create bad records. Mitigate with reconciliation jobs, contract tests, canary rollouts, and alerts on invalid currency or amount distributions.

Ramp-up: Plan for one pilot sprint plus one hardening sprint for a typical Laravel team, with additional time for legacy data migration and API versioning. Invest in examples, code review checklists, and automated tests before broad rollout. The package is easy to start with, but the surrounding money-handling conventions are where TPMs should focus adoption governance.