Laravel Unit Laravel Package

Technical Evaluation

Architecture fit jobmetric/laravel-unit is a domain-utility library, not infrastructure: it occupies a narrow seam in the application layer and exposes units of measurement, conversion rules, and formatting. That is architecturally low-risk in the sense that it should not touch routing, auth, or persistence — but unlike a logging or translation helper, it carries business semantics. Two distinct concepts get conflated in most unit packages and the distinction drives the whole evaluation: (a) physical conversion (kg↔lb, m↔ft — a pure function, safe to depend on a library for), and (b) business units (SKU pack sizes, "case of 12", billable hours, packaging tiers) which are policy, not physics, and must remain owned by the application. A TPM's first job here is to decide which of the two the package is being adopted for. If the answer is (a), leverage the library and wrap it. If the answer is (b), do not let a 6-star package become the source of truth for pricing or inventory semantics. The release notes describe only dependency bumps on a companion "core" package, so the package itself appears to be a thin configuration-and-conversion layer over a coupled upstream — meaning its supported behavior is partly determined by a second dependency with its own release cadence.

Integration feasibility Installation is standard Laravel (composer require, provider auto-discovery, config publish, possibly a migration for a units table). The friction is not installation, it is verification: a unit package can install cleanly and be wrong. Feasibility is gated on answering whether conversion is done with float or decimal arithmetic, what the rounding policy is, and whether non-multiplicative (affine) conversions such as Celsius↔Fahrenheit are supported at all. Each of those is a question the changelog and description do not answer.

Technical risk

Key questions

1. Does conversion use decimal/BrickMath-style arithmetic or native floats, and what is the documented precision and rounding contract?
2. Are unit definitions stored in config, in a published database table, or both — and does adopting the package create a schema and seed-data obligation?
3. Is there a canonical/base unit per dimension, and does the package enforce dimensional compatibility (rejecting kg→litres) or permit it?
4. Does it support offset conversions (temperature) and non-convertible units (currency, count-of-items)?
5. What is the public API surface — a facade, an Eloquent cast, a validation rule, or all three — and how stable is it across the 1.x line?
6. Are unit codes and labels localizable, and do labels route through Laravel's translator?
7. Who maintains the package, what is the issue-tracker response history, and is composer.json pinned to a Laravel range compatible with our target?

Integration Approach

Stack fit Good for a conventional Laravel application that needs display-layer conversion and consistent measurement formatting in forms and API responses. Poor fit as a system of record for commercial units. The correct posture is port-and-adapter: define an internal interface (e.g. UnitConverter) in application code, implement it with this package, and keep all call sites against the interface. Because the license is MIT, this also preserves the option to vendor the conversion tables and drop the dependency if maintenance lapses — a material de-risking fact for a 6-star package.

Migration path Scope the first integration to a read-only presentation concern, not a persistence concern. Concretely: pick one surface (product weight/dimensions displayed in a user-selected unit system), wire it through the adapter, and leave stored values untouched. Do not begin by converting stored data between units — that is an irreversible data migration and should be a separate, later decision with its own backfill and reconciliation plan. Only after the read path is proven should the team consider using the package's validation rules on input or an Eloquent cast on write.

Compatibility Two axes. First, framework support: confirm the composer.json constraint against the target Laravel and PHP versions before anything else, and check that the companion core package does not force an unrelated upgrade. Second, boundary compatibility: the unit codes exchanged with clients, ERPs, and carriers (ISO 80000, UN/CEFACT codes) are almost never the package's internal identifiers. Build an explicit mapping table at the API boundary and own it in application config — never let the package's internal unit keys leak into a public contract or a partner integration.

Sequencing

1. Spike on a branch: verify arithmetic model, rounding, dimensional checks, and affine support against a small fixture set with known-good values.
2. Wrap in an internal adapter; add unit-conversion round-trip tests to CI with tolerance assertions.
3. Ship the read-only display path for one attribute on one surface; instrument it.
4. Extend to input validation and formatting.
5. Evaluate persistence normalization (store canonical base unit) as a discrete, reviewed change.
6. Only then consider commercial/pack-size units, and model those in application code, not the package.
7. Record the decision and the pinned version in the dependency register.

Operational Impact

Maintenance Low ongoing change velocity, which cuts both ways: few breaking releases, but also few fixes. Budget a recurring review slot to check the package and its core dependency for releases, and pin exact versions in production rather than floating. The real maintenance burden is internal: someone must own the precision and rounding policy, the unit-code mapping table, and the fixture set. Treat those as application assets, not package configuration.

Support No evidence of a support model, SLA, security disclosure process, or responsive triage. Plan for source-reading as the primary support mechanism and assume the team may need to patch the package itself. MIT licensing makes that legally clean; it does not make it free. Confirm before adoption that at least one engineer is willing to read and, if necessary, fork the conversion tables.

Scaling Conversion is CPU-cheap and will not be a throughput bottleneck. The scaling risk is structural: if unit definitions live in a database table, every conversion or validation path that resolves a unit becomes a query unless the registry is cached — cache the unit registry at boot and warm it as a deploy step. The larger scaling concern is organizational: as more teams consume units, the mapping table and rounding policy become shared contracts and need an owner, versioning, and change review, or you get per-team conventions that fail to reconcile.

Failure modes

• Silent numeric error: float arithmetic or a wrong factor yields plausible but incorrect quantities. Mitigation: fixture-based tests with tolerance bounds and a periodic reconciliation check on any aggregated quantity.
• Rounding accumulation: per-line rounding summed across an order drifts from the rounded total. Mitigation: define and enforce a single rounding policy (round-on-aggregate vs round-per-line) in the adapter, not at call sites.
• Affine conversion gap: temperature or other offset conversions produce wrong values without raising. Mitigation: explicitly test them; if unsupported, block those dimensions at the adapter boundary.
• Dimensional mismatch: a caller converts kilograms to litres and gets a number. Mitigation: dimension validation in the adapter, plus a denylist of nonsensical pairs in tests.
• Code collision / case sensitivity: kg vs KG vs Kg resolve differently or shadow each other. Mitigation: normalize codes at the boundary.
• Orphaned dependency: package goes dormant and pins an old Laravel major, blocking framework upgrades. Mitigation: the internal adapter plus MIT source means the exit is a day's work, not a quarter's — but only if the adapter exists from day one.
• Commercial-semantics leak: pack sizes and billable units modeled as physical units, breaking when business rules change.

Ramp-up The API surface is small enough that a Laravel developer is productive in under a day. The expensive ramp-up is domain, not package: engineers need the precision policy, the rounding rule, the canonical-storage decision, and the unit-code mapping explained before they write conversion code. Budget a short design note and a shared fixture file as onboarding artifacts. Given the thin documentation and the low adoption signal, assume no institutional knowledge exists outside the team and write it down as you go — that document, not the package, is what makes this maintainable.