Math Laravel Package

Technical Evaluation

• Architecture fit: brick/math is a framework-agnostic utility library, not a Laravel package. It has no service provider, configuration, migrations, or HTTP surface, so it fits as a domain-level dependency rather than an application subsystem. It is best leveraged for bounded, precision-sensitive calculations: monetary proration, tax and FX conversion, metering, quotas, loyalty balances, scientific quantities, and large-integer identifiers. It should not replace database numeric types or become a general-purpose ORM abstraction.
• Integration feasibility: Very high. Installation is a single Composer dependency, and the API is small and immutable. The main gates are runtime prerequisites, not architectural ones: the current release line requires PHP 8.2+, which aligns with Laravel 11/12 but excludes older Laravel deployments unless an older 0.x cycle is pinned. GMP or BCMath is strongly recommended for production performance; the library falls back to pure PHP automatically, but that fallback has materially different throughput characteristics.
• Technical risk: Moderate but manageable. The package is still pre-1.0 and intentionally introduces breaking changes only at new 0.x cycle boundaries, so version pinning is a hard requirement rather than a best practice. The most important product-risk area is untrusted numeric input: of() is documented for trusted input, and an input such as 1e1000000000 can expand memory usage dramatically. Any user-supplied number must go through parse() with explicit syntax and maxDigits constraints. Additional risks include inconsistent rounding policy across teams, accidental float conversion at boundaries, and performance regressions in high-volume paths if GMP/BCMath is absent.
• Key questions: Which calculations are monetary versus general quantities, and what scale and rounding mode is authoritative for each? Where does untrusted numeric input enter the system, and who owns the validation contract? What PHP versions and extensions exist across local, CI, staging, and production? Will numbers be stored as decimal columns, strings, or normalized integers, and how will they be serialized through APIs and queues? Is raw arithmetic sufficient, or should the team evaluate brick/money for currency-aware behavior? What volume and latency envelope must precision-safe calculations meet?

Integration Approach

• Stack fit: Composer-native and compatible with Laravel's dependency injection and domain-service patterns. No framework wiring is required, but TPM should sponsor a thin internal convention: a calculation service or value-object layer that owns scale, rounding, parsing, and exception translation. Direct BigInteger/BigDecimal calls scattered across controllers, models, and jobs will create inconsistent behavior.
• Migration path: Introduce the package behind existing domain interfaces rather than rewriting calculations wholesale. Start with new features or a single bounded context, convert float-based calculations to BigDecimal or BigRational, and preserve legacy outputs through shadow calculations before cutover. For persistence, map database DECIMAL/NUMERIC columns or canonical strings into BigDecimal via custom Eloquent casts, and emit strings—not floats—through API resources. For untrusted input, standardize a parse()-based validator before any arithmetic method is called.
• Compatibility: Pin the package cycle to the platform's minimum PHP version. Current releases require PHP 8.2; PHP 8.1 can use 0.13, PHP 8.0 can use 0.11, PHP 7.4 can use 0.10, and PHP 7.1–7.3 can use 0.9. Ensure GMP or BCMath is installed consistently in Docker images and CI. The library's serialization is designed to remain portable across machines with different extensions, but application-level serialization—JSON, queues, cache—should still use explicit string representations rather than relying on implicit object behavior.
• Sequencing:
  1. Inventory precision-sensitive calculations and every external numeric input path.
  2. Define domain rounding modes, scales, and exception-to-API mappings with product and finance stakeholders.
  3. Spike the dependency on the target PHP version and verify GMP/BCMath availability.
  4. Build shared value objects, Eloquent casts, validators, and API formatting conventions.
  5. Migrate one bounded context with fixture-based tests and comparison against legacy outputs.
  6. Roll out behind feature flags, then expand to additional calculations.
  7. Add static-analysis guidance, document version-pinning policy, and formalize upgrade ownership.

Operational Impact

• Maintenance: Low ongoing maintenance for the dependency itself, but deliberate upgrade management is required because of the 0.x release model. Lock to a specific cycle, monitor changelogs and releases, and schedule upgrades as planned work rather than allowing automatic minor-version drift. MIT licensing keeps legal and distribution overhead low.
• Support: Community-supported open source with no vendor SLA. Internal ownership must cover version policy, rounding standards, input validation, and incident response. The small API surface and strong test posture reduce support burden, but the team should not assume the package author will provide application-specific guidance.
• Scaling: CPU and memory costs scale with digit count, scale, and operation complexity. GMP/BCMath should be treated as production requirements for high-volume paths, not optional optimizations. Enforce maxDigits on untrusted input, cap decimal scales, avoid unbounded exponent expansion, and keep large-number objects out of queue payloads where strings suffice. Database precision must match domain scale, or storage will silently undermine the library's guarantees.
• Failure modes: Expect RoundingNecessaryException when scale is insufficient, DivisionByZeroException, NumberFormatException, and possible memory exhaustion from oversized inputs. Extension differences, float conversion at API or database boundaries, and inconsistent rounding can produce silent financial errors rather than crashes. Catch the common MathException interface at domain boundaries and translate failures into explicit product behavior—especially for money, where failing closed is preferable to approximating.
• Ramp-up: Low for basic arithmetic; moderate for correct monetary modeling. Engineers need clear guidance on immutability, factory versus parse() usage, rounding modes, scale ownership, and exception handling. TPM should invest in a short internal standard, shared fixtures, and review checkpoints; the optional PHPStan extension can improve exception-type inference but is third-party and should be evaluated separately before adoption.