Unit Converter Laravel Package

Technical Evaluation

Architecture fit. jordanbrauer/unit-converter is a pure-PHP, dependency-light library built around a UnitConverter service, a unit registry, immutable Unit value objects, and a Conversion result object. It maps cleanly onto Laravel's container: the package ships a service provider (auto-discoverable) and a façade, so it can be resolved as a singleton and injected like any other domain service. There is no persistence, no queueing, no external I/O — it is a stateless computation library, which means it can sit inside domain services, form requests, API resources, or Blade components without architectural friction. The main architectural caveat is that it is a library, not a domain model: unit semantics your business cares about (which units are canonical for a SKU, rounding policy per channel) must live in your application layer, not in the package.

Integration feasibility. High for a proof of concept, moderate for production. Composer install is trivial; the façade gives a one-line UnitConverter::convert(1, 'kg')->to('lb')-style call. Custom units can be registered, which covers proprietary or regional units (e.g., a specific "case" or "pallet" unit) without forking. The real feasibility question is version support: verify the illuminate/support constraint and PHP constraint against your target Laravel version — an older package may not declare Laravel 10/11 compatibility even if it works, which forces a Composer --ignore-platform-reqs hack or a fork.

Technical risk.

• Maintenance signal. Zero dependents and negligible adoption is the dominant risk. Assume no upstream fixes; budget for a fork or in-house ownership from day one.
• Correctness of factors. Unit tables are the product. US vs. imperial gallons, short vs. long tons, fluid ounces, and temperature offset conversions (not pure ratios) are classic defect sites. Treat the factor table as untrusted until validated.
• Precision and rounding. Floating-point arithmetic with fixed precision will drift in financial or shipping-weight contexts. The package is not a decimal/money library; wrap results with bcmath or a rounding policy at the boundary.
• Scope limits. Expect no compound/derived unit algebra (kg·m/s²), no significant-figures handling, and limited locale-aware formatting.

Key questions.

1. Which Laravel and PHP versions are actually declared and tested, and is there a CI matrix?
2. How complete and how accurate is the conversion table for our specific unit families — and what is the provenance of the factors?
3. Does it handle temperature (offset) conversions correctly, and how does it round?
4. Is the registry mutable at runtime (can we register tenant-specific units per request safely)?
5. License and fork friendliness — can we vendor it and patch factors ourselves?

Integration Approach

Stack fit. Excellent for a Laravel monolith or modular monolith. Bind the package behind an application-owned interface (UnitConversionService) and treat the package as an implementation detail. That single adapter is the cheapest insurance policy available here: it caps the blast radius of abandonment to one file and lets you swap in php-units-of-measure, a bespoke table, or an external service later without touching call sites. Resolve the converter as a singleton in a service provider; keep configuration (default precision, canonical units per domain) in config/units.php.

Migration path. There is no migration in the data sense — this is additive. The path is: (1) spike in a throwaway branch to confirm the unit families you need are covered and the factors are right; (2) introduce the adapter interface with a small, deliberate surface (convert, convertMany, normalize); (3) port existing hand-rolled conversion arithmetic into the adapter and delete it; (4) only then expose it to controllers/jobs. If you have stored values in mixed units today, that is a separate data-normalization project with its own backfill and dual-write plan — do not conflate it with library adoption.

Compatibility. Two axes: framework version and unit semantics. Framework-wise, pin the package version and let Composer's platform checks fail loudly rather than silently. Semantics-wise, define your canonical internal units (SI where possible) and make conversion a presentation/ingestion concern only — never store converted values alongside originals without an explicit unit column.

Sequencing.

1. Week 1 — validation spike. Confirm Laravel/PHP compatibility, enumerate required unit families, and build a golden-file test suite of ~100 known conversions sourced from NIST or an equivalent authority.
2. Week 2 — adapter + guardrails. Wrap the package, add the golden-file tests to CI, and codify rounding policy.
3. Week 3 — first consumer. Ship one low-risk surface (e.g., a display-only conversion in an API resource or admin view).
4. Week 4+ — expand. Move to write-path conversions (shipping weight, recipe scaling) once the golden-file suite has run clean for a release cycle.

Operational Impact

Maintenance. Low effort, but nonzero ownership. Expect to own the dependency: vendor it, tag your fork, and keep the golden-file test suite as the contract. Because the package is small and pure PHP, a fork is genuinely cheap — that is the strongest argument in its favor despite the abandonment risk. Budget roughly a few days per year for dependency hygiene plus factor updates.

Support. No vendor, no SLA, no active community to lean on. Internal support means one or two engineers who understand the adapter and the factor table. Document the canonical-units policy in the repo, not in someone's head — this is the kind of decision that silently rots.

Scaling. Effectively free. Conversion is in-process arithmetic with no allocation pressure beyond value objects; it will never be your bottleneck. The only scaling-adjacent concern is per-request cost of building a large custom registry — register custom units once at boot, not per call.

Failure modes.

• Wrong factor — silent, plausible-looking output. Mitigation: golden-file tests, spot-check high-value units (mass, volume, temperature).
• Incompatible unit types — package throws; ensure exceptions are caught at the adapter and translated into validation errors, not 500s.
• Precision loss — compounding drift across multi-step calculations. Mitigation: convert once at the boundary, never in a loop.
• Division by zero / zero-magnitude edges and negative temperatures in offset conversions — cover explicitly in tests.
• Framework upgrade breakage — an unmaintained package can block a Laravel major upgrade. Mitigation: the adapter plus a fork you control.

Ramp-up. Hours, not days. The API is small and idiomatic; a mid-level Laravel engineer can be productive the same afternoon. The real ramp-up cost is domain knowledge — which units the business actually uses, which rounding is contractually required, and which conversions are regulated (shipping, labeling). Assign that knowledge to a named owner before the first production call site ships.