Math Laravel Package

Product Decisions This Supports

• Build vs. buy for money and quantity math. Adopt brick/math as the arithmetic primitive instead of building arbitrary-precision decimal/integer/fraction handling in-house. It is MIT-licensed, Composer-installable, and provides BigInteger, BigDecimal, and BigRational with immutable value objects — a low-cost foundation for billing, ledger, pricing, tax, payout, and usage-metering features.

• Feature scope for financial correctness. Use it when a product decision depends on exact arithmetic rather than IEEE-754 floats: proration, multi-line invoices, tax breakdowns, FX conversion, discount allocation, refunds, payroll deductions, loyalty points, prepaid credits, crypto/token amounts, or large IDs. The package makes rounding an explicit product policy via RoundingMode instead of an accidental side effect.

• Rounding and allocation policy as a product requirement. BigInteger::dividedBy() throws when a result is not exact; BigDecimal::dividedBy() requires a scale and optionally a rounding mode; BigRational keeps exact fractions. This forces PMs and finance stakeholders to decide “round half up, half down, down, or up” per use case — before engineering encodes a default. That is a product-governance win, not just a technical one.

• Trust boundary decisions for user-entered amounts. The README explicitly warns that of() is for trusted input, while parse() supports syntax restrictions and maxDigits for untrusted strings. This supports a security/product decision: user-supplied prices, quantities, rates, or invoice amounts must be parsed with limits, not passed directly into arithmetic methods. That prevents denial-of-service-style inputs such as extremely large exponents from becoming a production incident.

• Roadmap sequencing for a “money-safe” platform. If the roadmap includes subscriptions, marketplaces, multi-currency pricing, payouts, or financial reporting, this package is a near-term foundation rather than a later optimization. It can be introduced behind an internal Money/Amount value object without rewriting product surfaces, then extended as billing complexity grows.

• Laravel integration decisions. Use it in Eloquent casts (store as DECIMAL/string, hydrate as BigDecimal), form requests/validation, queued job payloads, and service-layer calculators. Because the objects are immutable and serialization is portable across machines with different PHP extensions, they are suitable for queue workers and distributed Laravel deployments. Avoid exposing BigDecimal directly everywhere; wrap it in domain types so the product can change arithmetic or currency behavior later.

• Build-vs-buy boundary at the “money” layer. brick/math is an arithmetic library, not a full money package. It does not provide currency semantics, formatting, allocation across line items, or database persistence. PMs should decide whether to build a thin internal Money abstraction on top of it or adopt a higher-level money package that depends on it. Either way, brick/math is the correct low-level primitive.

When to Consider This Package

Consider brick/math when:

• The product handles exact decimal or integer values where floating-point drift is unacceptable — money, tax, invoices, interest, points, quotas, metering, or scientific quantities.
• The team needs explicit, auditable rounding behavior rather than implicit round() calls scattered across controllers and jobs.
• Values can exceed native integer bounds or require more precision than a database DECIMAL column comfortably provides at the application layer.
• Inputs may be untrusted user strings, and the product needs bounded parsing (parse() with maxDigits and syntax limits) rather than unbounded conversion.
• The platform is on PHP 8.2+, ideally with GMP or BCMath installed for performance; the library selects the fastest available calculator at runtime.
• The team accepts pinning a 0.x release cycle. The README states breaking changes start a new 0.x cycle, so ^0.19-style constraints plus changelog review are required. This is stable enough for production but not semver-stable in the 1.x sense.
• You want a small, focused, MIT-licensed dependency rather than a large finance framework.

Look elsewhere or pause when:

• You need a full money/currency domain model with formatting, currency metadata, and allocation rules. Use brick/math underneath or choose a higher-level package.
• The use case is display-only formatting or simple counters that fit native integers. Arbitrary precision adds conceptual overhead without product value.
• The team cannot yet commit to PHP 8.2+ or to reviewing breaking changes between 0.x cycles.
• The requirement is database-side aggregation across millions of rows. brick/math is application-side; large-scale reporting may still need database decimal types, warehouse calculations, or a dedicated ledger design.
• The product needs cryptographic or blockchain-grade security guarantees. This is an arithmetic library, not a security or key-management solution.
• Performance is extremely hot-path-sensitive and native integers suffice. GMP/BCMath helps, but arbitrary-precision object math is still heavier than scalar arithmetic.
• The metadata’s dependent count is a decision input. Treat that snapshot as unreliable and verify real adoption through Packagist/downloads and transitive dependency inspection before using popularity as a proxy for maturity.

How to Pitch It (Stakeholders)

For executives: This is a small, MIT-licensed, production-used PHP library that reduces the risk of financial calculation errors in billing, invoicing, tax, payouts, and metering. It makes rounding rules explicit and auditable, supports exact decimal and fraction math, and avoids vendor lock-in. Adoption cost is low because it is Composer-installable and can be introduced behind an internal money abstraction. It is not a complete billing system and does not replace finance policy; it is the arithmetic foundation that makes those policies enforceable in code.

For engineering: brick/math provides immutable BigInteger, BigDecimal, and BigRational types with explicit rounding modes, fine-grained exceptions, portable serialization, and optional GMP/BCMath acceleration. It requires PHP 8.2+ and uses a 0.x release model, so pin the release cycle and review changelogs on upgrade. Use parse() with maxDigits for untrusted input, never pass raw user strings into of() or arithmetic methods, and wrap the library in domain value objects rather than letting it leak across the codebase. Avoid floats for monetary values entirely.

For product and finance stakeholders: The key decision this package forces is not “which library,” but “what is our rounding policy per product surface?” Once that is agreed, brick/math gives engineering a precise, testable way to implement it. Expect a modest upfront investment in money types, validation, and persistence conventions; the payoff is fewer reconciliation defects, clearer audit trails, and a safer path to multi-currency, usage-based, or marketplace pricing.