Bcmath Polyfill Laravel Package

Product Decisions This Supports

Roadmap: where our product must run. This package answers a specific go-to-market question: can we ship to environments where we can't install PHP extensions? If part of our addressable market is cheap shared hosting, managed WordPress-adjacent platforms, locked-down enterprise PHP images, or serverless/PaaS runtimes with a fixed extension set, this is the difference between "supported deployment target" and "won't install." That's a distribution decision, not a code decision — and it belongs on the roadmap next to our hosting/compatibility matrix.

Build vs. buy: do we require ext-bcmath or ship a fallback? The default PM answer should be require the extension — it's bundled with PHP, it's one docker-php-ext-install bcmath or one composer.json platform requirement away, and it's 10–100x faster than pure PHP. This package only earns its place when we can prove at least one real deploy target can't enable the extension. Treat it as insurance for a specific segment, not a default dependency.

Feature decisions it unblocks:

• Money and currency correctness — payment amounts, tax/VAT rounding, multi-currency conversion, invoice line totals, refunds and proration. Float math here produces cent-level drift that becomes chargebacks and support tickets; arbitrary-precision decimal math is the correct primitive.
• Regulated/compliance-adjacent calculation — payroll, interest accrual, fee schedules, where "we rounded differently" is an audit finding.
• High-precision domains — crypto/token amounts (18 decimals), loyalty points and wallet balances, ERP quantities and unit-of-measure conversions, large-ID and scientific computation.
• Supporting vendor libraries we don't control — many payment SDKs and accounting packages call bcadd()/bcmul() as global functions and simply fatal without the extension. That's the sharpest use case: we can't patch vendor code, so we polyfill the function namespace underneath it.

What it explicitly does not decide: it isn't a general "we need decimal math" answer. If we're writing the math ourselves, brick/math is the better-maintained, better-API choice. This package's only unique value is drop-in global function compatibility with the bc* signatures (including PHP 8.4's new rounding helpers), so unmodified third-party code keeps working.

Risk decisions it forces. At 2 stars and 0 dependents with a single maintainer, adopting this is a supply-chain decision, not just a technical one. Decide up front: pin exact version, add to SBOM, write our own conformance tests against ext-bcmath output, and accept the option of vendoring/forking (MIT makes that cheap).

When to Consider This Package

Consider it when all of these hold:

1. At least one production or customer-facing deploy target cannot enable ext-bcmath — verified, not assumed (php -m | grep bcmath, check Dockerfile/CI matrix, check the host's extension list).
2. Code on the critical path — typically a vendor SDK — calls bcadd/bcmul/bccomp as global functions, so we can't swap in an object-oriented library.
3. You specifically need PHP 8.4's new bcmath functions (bcfloor/bcceil/bcround behavior); otherwise phpseclib/bcmath_compat — which this package is derived from — is the more established ancestor.
4. The math is not in a hot loop. Arbitrary-precision in userland PHP is materially slower than the C extension; a pricing engine over millions of rows or a per-request batch recompute needs a benchmark before commitment.
5. Someone owns it: pinned version, conformance test suite, documented fallback plan if the maintainer disappears.

Look elsewhere when:

• You control the runtime — just require ext-bcmath and delete the whole category of problem.
• You're writing new math code — use brick/math (maintained, typed, well-tested, huge adoption) rather than polyfilling global functions.
• You need it in a hot path, or for very large precision/perf-sensitive workloads.
• Your compliance posture forbids low-adoption, single-maintainer dependencies — in which case fork it internally, or standardize on requiring the extension and drop the unsupported hosting tier from the matrix.
• Inputs are user-controlled, unbounded-precision values — arbitrary precision plus naive input handling is a cheap denial-of-service vector. Validate magnitude and scale first.

How to Pitch It (Stakeholders)

To executives (one paragraph): Some of our target customers run our product on hosting where PHP's math extension can't be installed — and without it, payment and invoice calculations either break outright or fall back to floating point, which silently produces rounding errors in money. This is a small, MIT-licensed, drop-in compatibility layer that lets the same code run correctly in those environments, so we can support that segment without maintaining a fork of our billing path. It's a low-cost enabler for a distribution decision, not a platform bet; the main trade-off is that it's an early-stage open-source dependency we'd pin, test, and be ready to vendor — a few days of engineering, no licensing cost.

To engineering (the practical case): Pure-PHP implementations of bcadd, bcsub, bcmul, bcdiv, bcmod, bcpow, bcsqrt, bccomp, bcscale, plus PHP 8.4's new rounding functions — same signatures, no extension, no compilation. Drop it in for environments lacking ext-bcmath, keep ext-bcmath required everywhere else so production stays on the fast C path. Do three things before merge: (1) a conformance test comparing every function's output against native bcmath across a fixture set including negative numbers, scale edge cases, division by zero, and huge operands; (2) a performance benchmark on our realistic worst-case batch to confirm request budgets hold; (3) pin the exact version, add it to the SBOM, and note that upstream is a single maintainer derived from phpseclib/bcmath_compat — so we can fork or swap to that ancestor if needed. Also gate it: only load the polyfill when !extension_loaded('bcmath'), and fail loudly in dev if a code path unexpectedly hits the slow implementation in a hot loop.

Bottom line for the go/no-go: adopt only as a scoped fallback for a proven, extension-less deployment target, with a conformance suite and a pin. Not as a default dependency, and not as our decimal-math strategy.