Math Php Laravel Package

Technical Evaluation

Architecture fit: markrogoyski/math-php is a pure-PHP, dependency-free numerical library with no Laravel coupling and no service infrastructure. For a TPM this is a low-friction “library” procurement decision rather than a platform one: it adds in-process compute capability (linear algebra, distributions, descriptive/inferential statistics, numerical analysis) without introducing a runtime, a queue, or a network hop. The v2.13.0 matrix column operations (columnAddScalar, columnSubtract, columnSubtractScalar, columnDivide) are the strategically interesting additions — they enable feature-scaling and data-transformation workflows to stay inside PHP/Laravel rather than being punted to a Python service or a BI tool.

Integration feasibility: High. Composer install, PSR-4 autoload, no migrations, no config publishing. The real effort is not wiring; it is validation and call-site triage. Treat the estimate as “a day to install, a sprint to trust.”

Technical risk: The headline risk is that v2.13.0 ships behavioral changes in a minor version. For a TPM this matters because it converts a routine dependency bump into a change-management event:

• Hard rename: SampleData\People::getShowSize → getShoeSize is a fatal error for any live caller.
• Sentinel-to-exception migration: correlation, effect-size (cohensQ, hedgesG, cohensD, glassDelta), divergence (kullbackLeibler, jensenShannon), stemAndLeafPlot, Grubbs outlier functions, and Experiment functions now throw where they previously returned NaN/INF/0/empty. Any Laravel controller or queued job that relied on tolerant return values will now 500 or poison a queue.
• Silent numeric drift: fractionalRanking (tie detection rewritten), cumulativeFrequency/cumulativeRelativeFrequency (semantics corrected), Hypergeometric::cdf (now summed PMFs), and geometricMean (log-space rewrite) change results without changing signatures. This is the higher-severity class because it does not self-announce and can quietly alter dashboards, pricing, risk scores, or model inputs.

Net assessment: the release is correctness-improving and should be adopted, but it is not a drop-in patch. The maintainers are applying semver loosely, which is a governance signal to pin exact versions.

Key questions:

• Do we actually consume SampleData, or is it only used in our test fixtures? (Changes the rename from “production incident” to “test cleanup.”)
• Which call sites currently swallow NaN/INF/empty arrays, and what is the desired behavior now that they throw — fail the request, degrade, or fall back?
• Do we have golden-file or snapshot tests on any user-visible numeric output that would surface drift?
• Is our product surface one where a wrong number is a trust/compliance event (finance, health, A/B test readouts)? If yes, weight this higher.
• Does the team have PHP numerics experience, or will we be reimplementing statistical routines badly if we skip this?

Integration Approach

Stack fit: Composer-native, autoload-compatible, no Laravel service provider required (none is evidenced). It behaves like any other computational utility — a dependency of domain/services classes, not of the framework layer. Recommended placement: behind thin application-level wrapper classes (e.g., App\Analytics\StatisticsService) so that the library is a swappable implementation detail and so we control the exception contract in one place.

Migration path:

1. Inventory — grep the codebase for MathPHP\SampleData, Statistics, Probability\Distribution, Trigonometry, Algebra. Produce a call-site register.
2. Classify each call site: (a) unaffected, (b) rename-only, (c) newly-throwing, (d) numerically sensitive. These have different owners and different remediation.
3. Remediate by class — rename getShowSize; wrap throwing paths with explicit handling and a documented product decision per site; snapshot-test numerics before and after.
4. Wrapper layer — introduce or extend the app-level facade so future upstream behavioral churn is absorbed in one file rather than N call sites.
5. Adopt new matrix features separately — do not combine the version upgrade and new-feature work in one change set; it makes regression attribution impossible.

Compatibility: Confirm the PHP version floor against composer.json (not stated in the release notes). The practical compatibility risk is numeric output drift, not language version. Pin to exact versions ("2.13.0") rather than ^2.13.

Sequencing:

• Pin the current version on the release branch; disable auto-upgrade.
• Feature-branch the upgrade; run the full suite plus any golden-file validations.
• Diff numeric outputs on the highest-value calculations (reports, scores, model features) before/after; every delta needs an explicit accepted-change sign-off from the product owner.
• Staging → canary (if the app serves live numeric output) → broad rollout.
• Only then begin adopting the new matrix column operations in new feature work.

Operational Impact

Maintenance: Low infrastructure cost, non-trivial governance cost. No services, no state, no persistence. The recurring burden is release-note triage: given the density of behavioral changes in a minor bump, someone must read every changelog before upgrading. Budget for this explicitly; it is the single largest ongoing cost of adopting this package.

Support: Community open source, no commercial support tier, escalation via upstream GitHub issues. The code is readable PHP and the surfaces we would depend on (descriptive stats, distributions) are reimplementable, so a maintainer stall is survivable — but only if we first document exactly which functions we call. Make that inventory a deliverable of the integration, not an afterthought; it is what makes a fork or replacement decision cheap later.

Scaling: In-process PHP compute. The concern is CPU-per-request for heavy workloads — matrix operations on large data and noncentral distribution functions (e.g., NoncentralT::median, numerical integration) can be slow. Anything user-facing must be benchmarked before shipping. Large matrices hit PHP array overhead, which is a hard practical ceiling, not a theoretical one. Guidance: put heavy numerics on queued jobs, cache expensive results, and keep request-path math to bounded, small-N operations.

Failure modes:

• Uncaught exceptions from the newly-throwing methods — 500s on request paths, retry storms / poison messages on queues. Highest frequency risk; mitigated by the wrapper layer and per-boundary policy.
• Silent numerical drift in fractionalRanking, cumulative frequency functions, Hypergeometric::cdf, and geometricMean — no exception, wrong numbers. Highest severity risk; mitigated only by snapshot testing and output diffing.
• Fatal error on the un-renamed getShowSize — only manifests when that code path executes, so staging coverage must actually exercise it (a real gap if it lives in a low-traffic admin or reporting path).
• Downstream ingestion of sentinel values — any pipeline that previously consumed NaN/INF/0 and now receives an exception will break in ways that surface as data gaps rather than errors.

Ramp-up: Low. No new operational concepts, no new runtime, no on-call surface of its own. Engineers familiar with Composer and basic statistics can be productive immediately; the learning curve is domain-math literacy, not tooling. The one thing to teach the team explicitly: this library now prefers to fail loudly, so error handling is a product decision each call site must make, not a boilerplate try/catch.