Better Units Laravel Package

Technical Evaluation

Architecture fit. BetterUnits is a framework-agnostic, pure-PHP domain library — no service provider, facade, config, or Laravel-specific bindings. That is actually an architectural positive: it can sit behind a Laravel service container binding and an internal UnitConverter contract without fighting the framework. It is stateless and computation-only, so it composes cleanly with value objects, form requests, and API resources. The gap is that we own the Laravel integration layer; nothing is provided.

Integration feasibility. Composer-installable under MIT, no known conflicting dependencies. Feasibility hinges on two unknowns we must verify in a spike: (1) the package's PHP version constraint against our Laravel runtime (Laravel 10/11 pins PHP 8.1/8.2), and (2) whether the unit registry covers the categories our product actually needs (length/mass/volume/temperature are table stakes; derived or compound units, data sizes, and currency-like units are where these libraries usually fall short). With 0 dependents and 2 stars, there is no ecosystem evidence that anyone has run this in a Laravel app — we would be the first, which converts an install into an evaluation project.

Technical risk. High, and concentrated in supply chain rather than code quality. Single maintainer, near-zero adoption, no downstream validation, and no apparent semver contract we can rely on. Conversion is numerically sensitive: floating-point rounding behavior, precision configuration, and exception-vs-silent-failure semantics on unknown units are all undisclosed risks that directly threaten correctness in any user-visible number. The license is permissive, which is the one strong mitigation — we can fork and vendor if the upstream stalls.

Key questions.

• Which unit categories and units are supported, and can custom units be registered?
• What is the rounding/precision model, and is it configurable per conversion?
• Does it throw on unknown units or fail silently?
• What PHP versions are supported, and is the versioning semver?
• Is there any test suite we can audit for accuracy, and is it actively maintained?
• Does it handle compound/derived units (e.g., kg·m/s²) or only single-dimension conversions?

Integration Approach

Stack fit. Zero framework coupling means it drops into any Laravel version that satisfies the PHP constraint. The right pattern is a thin internal adapter: a UnitConverter interface in our domain layer, a BetterUnitsConverter implementation, and a singleton binding in a dedicated service provider plus a config/units.php for default precision and aliases. Nothing else in the codebase should import the vendor namespace directly.

Migration path. If we already use phayes/php-units-of-measure or hand-rolled conversion helpers, do not swap in place. Write the internal contract first, implement it with the incumbent, then add a BetterUnits-backed implementation behind the same contract. That gives us a one-line rollback and makes the evaluation reversible. If this is greenfield, land the contract and adapter together and treat the vendor as an implementation detail from day one.

Compatibility. Verify the composer php constraint and run composer why-not against the target Laravel skeleton before committing. Check for any transitive dependencies that could collide with framework packages. Confirm behavior under our actual PHP minor version, not just the constraint's lower bound.

Sequencing.

1. Spike (1–2 days): install in a scratch branch, build a table of canonical conversion vectors, and diff output against known-good references across precision settings.
2. Adapter: ship the UnitConverter contract and BetterUnits implementation behind a config flag.
3. Pilot: enable in a single non-financial, non-regulated surface (e.g., a display-only measurement field) and observe.
4. Go/no-go gate: only promote to inventory, billing, shipping, or compliance-adjacent paths after accuracy sign-off and a maintenance assessment.

Operational Impact

Maintenance. The dominant cost is not integration but stewardship. With one maintainer and effectively no user base, assume we are the de facto maintainers. Budget for either (a) pinning to an exact version and freezing, or (b) forking under our org and vendoring — MIT permits both. The codebase is small enough that forking is a realistic, low-cost hedge rather than an escalation.

Support. No commercial support, no meaningful community. Internal ownership must be named explicitly, with an owner in the domain team rather than platform. Expect to answer our own questions by reading source.

Scaling. Negligible runtime footprint — pure computation, stateless, no I/O, horizontally trivial. If the unit registry is constructed per-request, memoize it in the container; otherwise there is nothing to tune. This is not a scaling concern at any realistic volume.

Failure modes. Ranked by severity: silent numeric drift from floating-point rounding (worst — corrupts data without erroring); unhandled units raising exceptions in user flows; breaking changes on a minor bump given unproven semver discipline; and upstream abandonment leaving us exposed to unpatched bugs. Mitigations: assert-based unit tests on conversion vectors in CI, explicit error handling at the adapter boundary, exact-version pinning with a lockfile, and a documented fork trigger.

Ramp-up. Low technical learning curve — small surface area, conventional PHP, readable source. The real ramp-up is domain literacy: engineers must understand precision, significant figures, and which conversions are legally or financially load-bearing. Pair the adapter with a short internal doc and a conversion test-vector fixture so correctness is encoded, not tribal knowledge.