Money Laravel Package

Product Decisions This Supports

Feature and roadmap decisions

• Any roadmap item that touches money — checkout, carts, pricing tiers, discounts, tax, invoicing, refunds, subscriptions, payouts, marketplace revenue splits — can be scoped with this as a settled foundation rather than an open build item. It removes "how do we do money math?" from the design debate.
• Unlocks multi-currency expansion as a configuration decision instead of a re-architecture: ISO 4217 currency metadata, minor-unit handling, and currency-aware scaling come with the package instead of being hand-rolled per market.
• Makes marketplace/split-payout models (shareholders, vendors, affiliates, installment plans) a product feature you can price and commit to, since split() and allocate() with explicit distribution modes exist out of the box.
• Enables cash-rounding markets (CHF, and similar coin-increment regimes) via CashContext — a genuine blocker in POS/retail contexts that many generic money libraries quietly mishandle.

Build vs. buy

• Buy the primitives: exact arithmetic, immutable value objects, currency data, rounding semantics, allocation algorithms. Build the business rules: which rounding mode applies where, tax jurisdiction logic, discount stacking, refund proration policy.
• The library deliberately refuses to pick business policy (it throws when rounding is required rather than guessing). That's the right seam — it converts "someone accidentally introduced a float" into a code-review-time decision, and forces rounding policy to be an explicit, documented product decision.

Decisions it forces into the open (and should)

• Rounding policy per money-moving surface: half-up vs. banker's vs. ceiling — and where the round happens. RationalMoney lets you defer rounding to the last step of a chain, which changes customer-visible totals versus rounding at each step. That is a product/pricing decision, not an implementation detail.
• Remainder destination: FloorToFirst (Fowler), FloorToLargestRemainder (Hamilton), FloorToLargestRatio, or separate line item. These produce different payouts to different people — legal and support exposure, so it needs an owner.
• Whether stored prices use default scale, CustomContext scale (4+ decimals for unit economics), or AutoContext (intermediate calculations only).

Operational/commercial value

• Deterministic, reproducible totals support reconciliation, dispute handling, and audit. "We can prove the number" shortens chargeback and finance escalations.
• MIT license, no vendor lock-in, no per-transaction cost, no external service dependency — a favorable line in both the cost model and the security review.

When to Consider This Package

Strong adoption criteria

• The application performs any arithmetic on money beyond formatting: sums, percentages, proration, FX, splits, taxes.
• Multi-currency is live or on the 2–4 quarter roadmap.
• There is a compliance, audit, or finance-reporting requirement where "off by one cent" is a real incident.
• The team is comfortable with value objects and explicit types; Laravel already in use on PHP 8.2+.
• You need allocation/splitting semantics (payouts, revenue share, installments) and would otherwise write and test that algorithm yourself.

Diligence items before committing

• Versioning is pre-1.0 (0.x), with breaking changes introduced as new 0.x cycles. Pin to a release cycle (e.g. 0.14.*) and budget an upgrade ticket per cycle rather than "composer update."
• ISO currency data updates for alpha-code lookups are treated as breaking changes; numeric-code and country-code lookups can shift in minor releases. If currency data feeds localized pricing or reporting, you want a test fixture and a review step on upgrades.
• Verify ecosystem adoption independently — the dependents count in this report reads as zero, which contradicts the package's reputation. Treat that as a reporting artifact to confirm, not a signal of abandonment, but confirm it before it becomes a procurement objection.

Look elsewhere when

• You need a payments gateway SDK, PCI scope reduction, or hosted checkout — this is arithmetic only; it will not move a single dollar.
• You need exchange rates, historical rates, or currency conversion data. The library supports conversion interfaces; you own the rate source, refresh cadence, and staleness policy.
• You expect Laravel-native batteries: no service provider, no Money Eloquent cast, no validation rule, no Blade directive, no config file. You will write a thin adapter layer — roughly a sprint-day of work, plus a cast and a formatting helper.
• You need tax/jurisdiction rules, invoicing documents, or ledger/accounting semantics. Different domain, different packages.
• PHP < 8.2. Older versions exist for EOL runtimes, but adopting a frozen branch on an EOL runtime is a compounding risk.
• Extremely hot code paths without GMP or BCMath installed — the README explicitly recommends both extensions for speed. On high-volume pricing loops, benchmark before assuming it's free.

How to Pitch It (Stakeholders)

To executives (one paragraph) We have a recurring class of defect where money totals drift by cents — from float rounding, percentage proration, split payouts, or multi-currency scaling. Every one of those is a support ticket, a reconciliation task, or a dispute. brick/money is a small, MIT-licensed, widely used PHP library that eliminates that class of defect by making monetary arithmetic exact and immutable, and by refusing to silently round. It costs nothing to license, has no external service dependency, and the integration work is a thin wrapper over our existing Laravel code. Recommendation: adopt it now, before multi-currency and marketplace payouts make the cost of retrofitting materially higher.

To engineering (the short version)

• Immutable Money value objects over exact decimal arithmetic (brick/math); no floats, no silent precision loss.
• Rounding is never implicit — a RoundingMode is required whenever a result can't be represented exactly, otherwise it throws. Fail loudly in dev, never in prod silently.
• RationalMoney chains operations as fractions and rounds once at the end, so multi-step pricing math matches finance's expected totals.
• Contexts model real-world constraints: DefaultContext (ISO scale), CashContext (coin increments), CustomContext (arbitrary scale for unit economics), AutoContext (intermediates only).
• split() and allocate() cover remainder distribution with named, documented algorithms — replaces hand-rolled logic nobody wants to own.
• Framework-agnostic; PHP 8.2+; recommend GMP or BCMath for speed.

Adoption plan and cost

1. One-time wrapper layer: a Laravel service provider (optional), an Eloquent cast storing minor units as integers, a Money validation rule, and a Blade/formatter helper. Estimate: 1–3 days including tests.
2. Pin to a 0.x.* release cycle; add a calendar reminder to review release notes each cycle, with special attention to currency-data changes.
3. Write down rounding and allocation policy per money surface (checkout, refunds, payouts, tax) before wiring the code — this is the actual deliverable; the library just enforces it.
4. Install GMP or BCMath in staging/production images; verify in CI.

Risk summary Low technical risk, low commercial risk (MIT, no lock-in), moderate governance cost (pre-1.0 versioning, in-house policy decisions). The main failure mode is adopting it without deciding rounding and remainder policy first — in which case you get exceptions in production instead of drift, which is better, but still an incident.