hitocean/distance-calculator
hitocean/distance-calculator is a Laravel/PHP package for calculating distances, likely between geographic coordinates. It offers a simple way to add distance calculations to your application, with a lightweight API for common distance needs.
Architecture fit. hitocean/distance-calculator is a single-purpose Laravel package whose scope — geospatial distance computation between two points (typically lat/lng pairs, and plausibly address strings via a geocoder) — is genuinely orthogonal to almost every application architecture. That is a double-edged property: because distance calculation is a pure, stateless utility, the package has a very small surface area to integrate against and cannot "infect" the host application's domain model. But it also means the package occupies a slot that is trivially filled by a 20-line Haversine function, a PostGIS/MySQL ST_Distance call, or a maintained library such as geocoder-php or brick/geo. Any architecture fit argument therefore has to justify why a package at all, not just whether this package works. On the evidence available (0 stars, 0 dependents, score 0.1), there is no ecosystem validation that this specific implementation is the right abstraction for our needs.
Integration feasibility. Integration itself is likely low-effort: the typical shape is a composer require, an optional service-provider registration, a config file for API keys or units, and a facade or injected service. The published release date of 2022-05-12 and MIT license make the code legally and mechanically consumable. The real feasibility question is dependency resolution — a package last released in May 2022 was built against PHP 8.0/8.1 and Laravel 8/9 idioms. If our target stack is Laravel 11/12 on PHP 8.3+, we should expect at minimum a composer.json constraint bump, and at worst an incompatibility with newer framework contracts (service provider signatures, config publishing, HTTP client changes from Guzzle 6→7). That is a one-to-two-day spike, not a one-hour drop-in.
Technical risk. The risk profile is dominated by abandonment, not by code quality we can observe. The repository is archived — the maintainer has explicitly declined future maintenance — and there are zero dependents, which means zero downstream pressure to fix defects and zero public bug surface to learn from. We would be the only operator of this code in the world. Specific risks: (a) transitive dependency drift as the framework advances; (b) unpatched security advisories in whatever HTTP client or geocoding SDK it wraps, with no upstream to ship a fix; (c) unverifiable assumptions about API provider terms, rate limits, and coordinate-system handling (WGS84 vs. local datums) baked in silently; (d) bus-factor of exactly zero maintainers. For a pure-math Haversine helper the risk is negligible; if the package is a thin wrapper over a paid geocoding API, the risk is materially higher because provider contracts change.
Key questions.
composer.json, and does it depend on any package that has since had a security advisory?Stack fit. Distance calculation is a commodity capability, and our stack almost certainly already has a better-hosted option: if we run MySQL 8 or PostgreSQL, ST_Distance_Sphere / PostGIS is a single query with no new dependency, no new failure domain, and no vendor risk. If distance is needed in PHP rather than SQL, a ~15-line Haversine helper committed to our own app/Support namespace is auditable, testable, and permanent. A package earns its place only if it provides something we would otherwise build — realistically, a geocoding integration with retry, caching, and provider abstraction. Everything else this package might do is a rounding error of code.
Migration path. Recommended path is extract, don't depend. Vendor the relevant source files into our codebase under the MIT license (retaining the copyright notice), rewrite the service-provider wiring to our own container bindings, and replace config-file indirection with our standard config/geo.php. This converts an abandoned third-party dependency into first-party code we own, which is exactly the right trade for a package of this size and this maintenance status. Only pursue composer require if the package turns out to wrap a geocoding provider whose API contract we do not want to reimplement — and even then, prefer the provider's own official SDK.
Compatibility. Assume nothing. Before any decision, run a spike that (1) checks composer.json platform requirements against our PHP/Laravel matrix, (2) installs into a throwaway Laravel skeleton on our current version, (3) exercises the public API against known coordinate pairs with expected distances, and (4) audits transitive dependencies for advisories. Treat a failure at step 2 or 4 as a hard stop on the composer path and fall through to vendoring.
Sequencing. (1) Requirements clarification — confirm whether we need coordinate math only or geocoding too. (2) Spike and compatibility audit, timeboxed to two days. (3) Decision gate: native SQL / first-party helper / vendored code / official provider SDK. (4) Implement behind our own interface (DistanceCalculator contract) so the underlying implementation is swappable, which de-risks the decision entirely. (5) Golden-file tests with published reference distances so any future swap is verifiable. The interface step is the important one — it makes this a reversible, low-stakes decision rather than an architectural commitment.
Maintenance. This is the decisive factor. An archived repository with zero dependents means the maintenance burden transfers entirely to us on day one. There will be no upstream CVE patches, no framework-compatibility releases, and no issue tracker to search when something breaks in eighteen months. Owning ~200 lines of vendored math is a maintenance cost measured in hours per year; owning a dependency on an archived package is a recurring audit finding. Under any reasonable TCO model, the dependency path is more expensive than the copy path for a package this small.
Support. Internal support only. No community, no vendor, no SLA. Onboarding documentation must therefore be written by us, not inherited — which again argues for first-party code where the documentation and the implementation live together.
Scaling. Near-zero concern if the package is local math: Haversine is O(1) per pair, CPU-negligible, trivially cacheable. If it calls an external geocoding API, scaling becomes a rate-limit, cost, and latency problem, and the package's lack of maintenance becomes acute because provider APIs and pricing change frequently. In that scenario the correct move is to put our own cache and circuit breaker in front of it regardless of which client library we use, so the package's identity stops mattering. For bulk/nearest-neighbour workloads (e.g. "find the 10 nearest depots to this address"), neither this package nor a PHP helper is the right tool — that belongs in the database with a spatial index.
Failure modes. (a) Silent unit or datum mismatch producing plausible-but-wrong distances — the most dangerous failure, because it passes smoke tests and surfaces as a business-logic bug months later; mitigate with golden-file tests against published reference values. (b) Framework upgrade breaks the package's service provider and the app fails to boot — loud, easy to catch in CI. (c) Provider API key expiry or quota exhaustion if it wraps an external service — mitigate with explicit error handling and alerting. (d) Transitive dependency CVE with no upstream fix — mitigate by not taking the dependency. (e) Composer resolution deadlock alongside a modern Laravel version — an afternoon lost, not a production incident.
Ramp-up. Very low for engineers; a competent PHP developer understands the geospatial math in under an hour, and the integration surface is one or two call sites. The ramp-up cost is entirely on the decision side — someone must do the two-day spike and read the source to answer the key questions above. That reading is also the deliverable that makes vendoring cheap, since after reading it we have effectively already absorbed it.
Recommendation. Do not add hitocean/distance-calculator as a composer dependency. Prefer native spatial SQL if the distance is needed alongside stored data; otherwise vendor the MIT-licensed logic into a first-party helper behind a DistanceCalculator interface with reference-value tests. The opportunity score of 13.09 and the archived status are consistent with a package that has served its purpose and should be treated as reference source code rather than a live dependency. The single condition that would change this recommendation is discovering that the package encapsulates a geocoding integration we would otherwise have to build — in which case evaluate the provider's official SDK first, and this repository only as a design reference.
How can I help you explore Laravel packages today?