Laravel Bcmath Cast Laravel Package

Product Decisions This Supports

• Precision-critical feature work becomes unblocked. Any roadmap item where money, tax, unit price, quantity, or contractual rates must be exact — invoicing, billing, payouts, commission splits, subscriptions with proration, quoting, marketplace fees — stops being a "we'll handle rounding later" conversation. The cast lets engineering write $invoice->subtotal - $invoice->discount directly on model attributes with arbitrary precision, which shortens the path from spec to shippable code.
• Build vs. buy tilts toward buy, with a caveat. The package is one Eloquent cast class over PHP 8.4's built-in BCMath\Number. Building this internally is a day of work, so the real decision is not "buy vs. build" — it is "buy vs. build vs. do nothing." Choosing this package is a cheap decision; the expensive decisions it forces (schema audit, rounding policy, API serialization contract) are the ones worth the roadmap discussion.
• It surfaces a latent liability you probably already own. Adoption forces an inventory of FLOAT/DOUBLE columns holding currency or rates. Even if you defer the package, that audit is a legitimate roadmap item with its own risk-reduction value — float money columns are a correctness bug waiting for a reconciliation to expose it.
• It does not decide your money model. No currency handling, no minor-unit representation, no allocation/splitting, no FX, no formatting. It is a precision primitive, not a payments layer. Any roadmap item requiring those capabilities still needs separate design — do not let adoption create the impression that the money problem is solved.
• It creates a serialization/API versioning decision. Decimal attributes serialize as JSON strings, not numbers. That is semantically correct, but it is a breaking change for mobile clients, TypeScript interfaces, and any downstream consumer doing client-side arithmetic. Treat this as an API version bump with a coordination plan, not a Composer update side effect.
• Use it as a forcing function on rounding policy. The cast yields a value; it imposes no scale, rounding mode, or intermediate-precision policy. Those are product decisions (do we round at line item or at invoice total? which rounding mode?) that stay entirely with you — adoption is a good moment to write them down and assign an owner.

When to Consider This Package

Consider it when all of the following hold:

• Your stack is already on PHP 8.4+ and Laravel 12+, or is independently committed to getting there on its own business case. Laravel 11 support was dropped in v1.2.2 with no shim — there is no degraded mode, Composer simply refuses to install.
• You have decimal-bearing attributes where exactness is contractual or audited: prices, tax rates, quantities, line-item amounts, FX rates.
• Your schema is, or can be, converted to DECIMAL with explicit precision and scale. On FLOAT/DOUBLE columns the cast delivers zero correctness benefit — the schema work is the actual value, the cast is the ergonomics.
• Domain services do not consume Eloquent models directly, or you are prepared to accept a silent type shift from string to BCMath\Number inside every reader of that attribute.
• You can tolerate being an early production consumer of a two-star, single-maintainer, zero-dependent package — mitigated by the fact that the hydrated type is a PHP language built-in, so the blast radius is roughly one class of reimplementation under MIT.

Look elsewhere or defer when:

• You are on Laravel 10/11 or PHP < 8.4 and an upgrade is not already funded. Do not start a framework upgrade to adopt this.
• You need currency-awareness, minor-unit accounting, allocation/splitting across line items, or FX conversion — this package deliberately does none of that.
• You need vendor guarantees: security policy, LTS/deprecation policy, support SLA, published production references. None exist here.
• Your decimal attributes are read by many uncontrolled consumers (PDF generators, CSV/Excel exporters, search indexers, analytics pipelines, third-party SDKs, mobile clients) and you cannot inventory and coordinate them.
• You want rounding and scale governed by the tool. It is not; it must be governed by you, in FormRequest validation and domain policy.

How to Pitch It (Stakeholders)

To executives — one paragraph: We have a small, low-cost opportunity to eliminate a class of money-rounding errors that typically only shows up in a finance reconciliation. PHP 8.4 and Laravel 12 introduced native arbitrary-precision decimal objects; this MIT-licensed package connects them to our models so engineers can write ordinary arithmetic on prices and totals without losing cents. The package itself is trivial to install and trivial to remove — the real work, and the real value, is the associated audit of float-typed money columns and a written rounding policy, both of which we should do regardless of whether we adopt this. The risk is vendor immaturity, not technical fragility: it is a two-star, single-maintainer project. We mitigate that by depending on PHP's built-in BCMath\Number rather than on any vendor-owned class, so if the project disappears we rewrite one cast class and keep our data. Recommendation: pilot on one low-risk model with an acceptance test suite, gated on confirming our PHP/Laravel versions.

To engineering — the ask:

• Confirm the version matrix across every app, internal tool, export job, and reporting service that hydrates these models. Hard gates: PHP 8.4+, Laravel 12+.
• Complete the FLOAT/DOUBLE → DECIMAL schema audit as a prerequisite deliverable with its own owner and estimate, not a follow-on task.
• Pilot on one model with an explicit acceptance suite: string→Number, Number→round-trip, null, 0, empty string, values exceeding column precision failing loudly rather than truncating, and scale assertions. Round-trip fidelity has already been a defect class upstream (v1.2.2: "align set() input validation with what get() can parse back"), so we write our own tests rather than trusting theirs.
• Roll out model by model as independent, revertible PRs — no sweeping change; bisecting a regression should be cheap.
• Enforce input validation in FormRequests, not the cast. The cast accepts floats with a warning, and a warning is not a guardrail.
• Establish aggregate parity: verify SQL SUM() over DECIMAL agrees with PHP-side reduction over Number objects on representative data. Divergence surfaces in reconciliation, not in CI.
• Agree the exit trigger up front: 12 months of upstream inactivity, a breaking change to BCMath\Number in PHP, or any unresolvable round-trip defect.
• Codify the scope rule in an ADR: currency, tax rates, unit prices, quantities, and contractual-precision fields use AsDecimal; counters, IDs, sequence numbers, and analytical aggregates stay native. Without this rule the cast spreads into fields where it adds cost without correctness.