Laravel Money Laravel Package

Product Decisions This Supports

• Build vs. buy for money handling. The core value is not the money math—it's brick/money, a mature, widely used library. This package is a thin Laravel adapter (cast + parser + validation rule). That makes the real decision "do we adopt brick/money and write ~200 lines of glue, or take the glue off the shelf?" Frame it as: adopting brick/money is the architectural decision; this package is a convenience layer on top.
• Database schema decisions, now. The recommended storage pattern (bigInteger amount in minor units + string(3) ISO currency) is a durable, precision-safe schema. Adopting this package effectively locks in that decision early, which is exactly the kind of cheap-to-decide-now, expensive-to-change-later call a PM should force during greenfield design.
• Multi-currency roadmap sequencing. MoneyCast::of('currency') (currency per row) vs. MoneyCast::of('USD') (fixed currency) is a concrete fork in the roadmap. Choosing the column-based cast costs almost nothing today and preserves the option to sell into EU/UK/JPY markets later without a migration. If multi-currency is on the 12-month roadmap, this is the cheap option-preserving move.
• Where precision bugs are allowed to happen. The MoneyParser and ValidMoney rule let you decide, per surface, whether float input is tolerated at the edge (forms, CSV imports, third-party APIs) and normalized to exact values at the boundary—rather than scattering round() calls through checkout, invoicing, refunds, and payouts.
• Pricing and billing surface consistency. Any feature touching invoices, subscriptions, credits, refunds, discounts, or tax lines benefits from a single value-object type instead of ad-hoc decimals/ints. This reduces "the total doesn't match the line items" class of support tickets, which is a real support-cost lever.
• Validation as product policy. ValidMoney(nullable, min, max) turns business rules (no negative refunds, max order value for fraud review, optional price fields) into declarative constraints in Form Requests and Livewire components—cheaper to audit than scattered controller conditionals.

When to Consider This Package

Adopt when most of these hold:

• The stack is Laravel 10–12 and the team already thinks in Eloquent casts and Form Requests.
• You are greenfield or adding a new money-touching module (invoicing, billing, payouts, marketplaces) where you control the schema and can use bigInteger + currency from day one.
• You need multi-currency support per record, not just a single store currency.
• The team is small and Laravel-idiomatic; the cost of writing and maintaining this glue in-house exceeds the cost of a dependency.
• You want type safety at the model boundary (immutable Money objects) without a broader DDD refactor.
• You are willing to wrap it behind your own abstraction (see pitch below) so a swap is a one-file change.

Look elsewhere or build it yourself when:

• Currency conversion, FX rates, or a ledger is required. This package stores and validates; it does not convert. That's a separate decision (FX provider, rate snapshotting, audit trail) and should be scoped independently.
• Existing schemas store money as decimal/float. Migration to minor-unit integers is a data-migration project with rounding-policy and reconciliation work—not a package-adoption task. The package will work, but the cost is in the migration, not the dependency.
• API contracts are already fixed to string amounts ("USD 100.00"). Note the v2.0.0 breaking change: serialization now returns a float (100.00) instead of a string. Floats at a JSON boundary are a precision and contract hazard; if your clients consume money as strings, you must override serialization deliberately.
• Vendor-risk tolerance is low. 19 stars, 0 dependents, a single primary maintainer, and a namespace rebrand (Finller\Money → Elegantly\Money at v2.0.0) that already forced a search-and-replace migration. Treat this as a thin, replaceable utility, not infrastructure. If procurement requires a supported vendor or SLAs, this fails that bar.
• High-throughput hot paths. Casting and parsing per request is cheap, but if you're processing payments at scale, benchmark the cast on your heaviest query paths rather than assuming.
• You need formatting/localization (locale-aware display, symbol placement, rounding display rules). brick/money covers a lot, but display formatting is usually a presentation-layer concern you'll own anyway.

How to Pitch It (Stakeholders)

To executives (one paragraph): Money bugs are expensive and visible—wrong totals, mismatched invoices, refund discrepancies, and failed audits. This package is a small, MIT-licensed adapter that makes Laravel store and handle money exactly (integers in minor units, explicit currency codes) instead of approximately (floats). The underlying math library is mature and widely used; what we're adopting is the Laravel glue, roughly a day of work we don't have to write or maintain. It costs nothing, it's removable, and it preserves our option to sell in multiple currencies later. The risk is that it's a small open-source project with a single maintainer, so we'll isolate it behind our own internal type and pin the version—meaning if it's ever abandoned, we replace one file rather than refactor the product.

To engineering (the ask):

• Add elegantly/laravel-money as a pinned dependency; standardize money columns as bigInteger (minor units) + string(3) ISO currency.
• Use MoneyCast::of('currency') by default—even for single-currency tables—so multi-currency is a data change, not a schema migration.
• Do not let Money objects reach JSON directly. The default cast serializes to float; define an explicit API representation (string amount + currency code, or integer minor units + currency) in a Resource/DTO layer and test it.
• Centralize parsing at the edges (imports, webhooks, third-party APIs) via MoneyParser; apply ValidMoney with explicit min/max/nullable in Form Requests and Livewire.
• Keep a thin internal wrapper (e.g., App\Support\Money) around the cast and parser so the package is swappable if the project stalls.
• Validate edge cases before rollout: negative amounts (refunds/credit notes), zero-decimal currencies (JPY, KRW), rounding mode behavior (configurable in MoneyParser since v2.3.2), and legacy rows with missing or invalid currency codes.

Scope boundary to state explicitly: this package handles storage, casting, parsing, and validation. It does not handle FX conversion, rate history, ledgers, or financial reporting. If those appear in the roadmap, they are separate decisions with separate budgets—don't let this adoption imply they're solved.