Php Bignumbers Laravel Package

Technical Evaluation

Architecture fit. litipk/php-bignumbers is a framework-agnostic value-object library: immutable big-number types with arithmetic, comparison, and conversion operations, sitting over a pluggable arithmetic provider (GMP, BCMath, or pure PHP). That places it squarely in the domain layer of a Laravel application, not in HTTP, persistence, or orchestration. The realistic targets are bounded contexts where floats are a latent correctness bug: billing and invoicing, tax/VAT and fee accrual, currency conversion, loyalty points and credits, metering/usage rollups, crypto-adjacent balances, and scientific or telemetry measurement. It should never appear in a controller, a Blade view, or an Eloquent model's raw attributes; it belongs inside application services and domain DTOs behind an application-owned contract. Because there is no service provider, facade, config file, or publishable migration, the package is architecturally "invisible" — cheap to introduce and, importantly, cheap to remove. From a TPM perspective that structural isolation is the single strongest argument in its favor, and it is the property we should design to preserve regardless of which library ultimately backs it.

Integration feasibility. Composer-only with PSR-4 autoloading; no framework wiring, no bootstrapping, no migrations. A spike is measured in hours. The real feasibility question is not installation but the arithmetic backend, which becomes an environment-contract problem: GMP and BCMath are fast but must be present in every runtime — local dev, CI, container build, queue workers, scheduled jobs, and any lambda/edge runtime. The pure-PHP fallback removes the extension dependency at a substantial performance cost and with its own behavioral surface. Persistence is the second gap: there is no first-party Eloquent cast, so storing values means a custom cast over string or decimal columns plus a documented serialization contract for queues and JSON APIs. Static analysis will need a baseline because the source predates modern type declarations.

Technical risk. High, and driven almost entirely by lifecycle rather than by design quality. The repository is archived with a final release dated 2017-08-31, which means PHP 7.0-era code: no scalar or return type declarations, implicit-nullable parameters that become deprecations in PHP 8.4, dynamic-property patterns that fail on future majors, and no #[\ReturnTypeWillChange] annotations. Expect deprecation noise on PHP 8.1–8.3 and real breakage on a future major with no upstream remedy. There is no security disclosure process, no maintainer, and no release cadence. Ecosystem validation is thin: 129 stars and effectively zero dependents means few production war stories and no downstream pressure keeping the behavior correct on modern runtimes. In-repo tests exist but CI is dead, so they prove nothing about PHP 8.2+. The MIT license is the one meaningful mitigation — it permits vendoring or forking, which is the only defensible production posture.

Key questions.

• Is arbitrary-precision decimal arithmetic actually required, or would fixed-scale integer-cents arithmetic satisfy the domain? If the latter, this package is unnecessary complexity.
• Which PHP versions and extensions must be supported, and does the library load and pass characterization tests on the oldest and newest of them?
• Who owns the fork, and what is the patching SLA when a PHP upgrade or a CVE forces a change?
• Does the scale and rounding model match our accounting policy — rounding mode, scale enforcement, banker's rounding, tie-breaking?
• How are values serialized across queues, JSON APIs, and the database without precision loss or float coercion?
• What is the credible maintained alternative (brick/math, phpseclib BigInteger, or a thin internal wrapper over native BCMath/GMP), and what is the switching cost if we defer that decision?

Integration Approach

Stack fit. Neutral-to-weak at the framework level, strong at the domain level. Laravel does not need big numbers; the accounting and measurement domains do. Adoption should therefore be scoped to one calculation-heavy service or module, and the library should sit behind an application-owned interface — a DecimalMath, MoneyCalculator, or Quantity contract — rather than being imported directly into domain code. That single indirection converts an abandonment risk into a swap cost measured in one adapter class. It also lets finance and product state precision and rounding policy once, in a contract, instead of relying on whatever the library's defaults happen to be.

Migration path. Treat this as vendor-and-wrap, not adopt-upstream. Install via Composer for the spike; validate precision, rounding, comparison, and overflow semantics against golden datasets drawn from real historical transactions; then, if it survives, mirror the source into an internal namespace or point a Composer repositories VCS entry at our own fork, so we control PHP-version patches. Because the API is immutable value objects rather than shared mutable state, the escape hatch to brick/math is a reimplementation of the adapter plus a re-run of the same golden tests — a bounded, testable change rather than a rewrite.

Compatibility. Three axes must be verified before any production commitment. First, PHP version matrix: at minimum 8.1–8.3, ideally 8.4, with a recorded pass/fail per version. Second, extension availability per environment: document the GMP > BCMath > pure-PHP fallback order and prove the fallback produces identical results, not just acceptable ones. Third, persistence fidelity: DECIMAL column precision must exceed expected value magnitude by a margin, JSON must carry strings rather than floats, and queue payloads need an explicit serialization contract. Eloquent casts, API resources, and job payloads all need written rules, and static analysis will need a baseline file for the missing type declarations.

Sequencing.

1. Spike on a branch: install, run a representative calculation set on current PHP 8.x, capture deprecations, and compare backend behavior.
2. Define the internal decimal/money contract and write characterization tests covering rounding, scale, comparison, and overflow.
3. Implement the adapter over the library, plus a second adapter (BCMath or brick/math) behind the same contract for differential testing.
4. Harden persistence: custom cast, migration to string/decimal columns, serialization tests for API and queue boundaries.
5. Decide fork versus replace based on the measured PHP-upgrade delta, then and only then promote to customer-facing paths.

Operational Impact

Maintenance. Effectively 100% internal from day one. Because upstream is archived, every future PHP minor becomes our problem: deprecation cleanup, signature updates, and any behavioral drift in the pure-PHP provider. Budget a small recurring line item — a few engineer-days per PHP release cycle — and name a single owner. Vendoring into our namespace is the only defensible posture; continuing to resolve an archived package from Packagist is a supply-chain and availability gamble for a money path. This cost should be presented to stakeholders explicitly, because it is the price of the "free" MIT dependency.

Support. No vendor, no maintainer, no roadmap, no security contact, no CVE process. Support is entirely what we build: internal documentation, golden datasets, a documented rounding policy, and an escalation path. Community support is thin — 129 stars and no dependents means Stack Overflow and issue archaeology will yield little — so a second engineer must be able to reason about the semantics independently. The real support requirement is bus-factor mitigation: at least two engineers who understand scale, rounding mode, and which backend each environment runs.

Scaling. Adequate for domain-level arithmetic, poor for volume. With GMP or BCMath, millions of operations per batch are acceptable. The pure-PHP provider is orders of magnitude slower and will dominate CPU in reporting jobs, ledger reconciliation, or per-request line-item loops — precisely the workloads where big numbers appear at scale. Immutability means every operation allocates a new object: excellent for correctness, noticeable in tight loops. String serialization inflates memory in long-running queue workers, so batch sizing and worker recycling need tuning once real volumes arrive.

Failure modes.

• Silent precision loss at boundaries: floats leaking in through JSON, (float) casts, or DECIMAL columns narrower than the computed scale.
• Backend divergence: GMP locally, BCMath or pure-PHP in production, yielding different results or limits for identical inputs.
• PHP upgrade breakage: deprecations escalating to errors, signature incompatibilities, or dynamic-property failures on a future major — with no upstream fix.
• Serialization fragility: big numbers crossing queues and APIs as undocumented strings, or Eloquent rehydrating them as floats.
• Abandonment under pressure: a CVE or runtime requirement forces patching a frozen codebase on someone else's timeline.
• Rounding ambiguity: implicit default scale or rounding mode diverging from finance's stated policy, discovered during an audit rather than in tests.

Ramp-up. The API surface is learnable in a day — arithmetic, comparison, and formatting on immutable values read naturally. The conceptual ramp is steeper than it looks. Engineers must unlearn float habits, internalize why scale and rounding mode are explicit inputs rather than defaults, and know which backend each environment uses. Plan a short internal note with hard rules: always construct from strings, never floats; always specify scale and rounding explicitly; persist as strings or decimals, never as floats; never expose these types directly in API resources without a serialization contract; and route all arithmetic through the application-owned interface so the backing library stays swappable. Pair that with a review checklist item and a lint rule against float casts in the affected modules.