Product Decisions This Supports
- "Near me" / store-locator / dealer-finder features. This package sits in the capability class that powers any "closest X to me" surface: store locator, pickup point selector, service-area checker, marketplace supply-demand matching, delivery-zone eligibility, and distance-tiered pricing (e.g. free delivery within 5 km).
- Build vs. buy, resolved on the wrong axis. The math here (a straight-line Haversine formula plus unit conversion) is commodity — roughly 20–40 lines of code and an hour of engineering. The genuine buy decision is the layer above it: geocoding (address → lat/lng), routing/ETA, and the spatial index that makes radius queries fast. A PM who evaluates this package as "the distance feature" will under-scope the project by an order of magnitude.
- Roadmap sequencing for geo capabilities. Use this as the floor of the ladder: straight-line radius filter → bounding-box prefilter + Haversine → proper spatial index (PostGIS/MySQL
ST_Distance_Sphere, Redis GEO) → routing vendor for ETA. Deciding which rung the roadmap actually needs is a PM call driven by accuracy tolerance and dataset size, not a library call.
- Cost-control decision on routing APIs. Straight-line distance as a cheap prefilter before calling a paid routing/ETA vendor measurably reduces per-request spend — a legitimate reason to keep a Haversine helper in the codebase even after you buy a routing provider.
- Risk/technical-debt triage. An archived, zero-dependent, zero-star dependency is a liability line item, not a capability line item. Its real product value is as a reference implementation that justifies writing the helper in-house under your own tests and Laravel version support.
When to Consider This Package
Consider it (narrowly) when:
- You need a one-off straight-line distance calculation inside a small internal tool — a back-office radius filter, an admin report, a prototype — where a few thousand rows and no SLA make an unbounded Haversine scan acceptable.
- You want a copy-paste reference for the formula and its unit handling (km vs. miles, coordinate order pitfalls). MIT licensing makes lifting the logic into your own
Geo helper trivially legal, and that is almost certainly the right use.
- You are spiking a feature for a demo next week and the alternative is no geo capability at all.
Look elsewhere — decisively — when:
- Production dependency. Last release May 2022, archived, 0 stars, 0 dependents. That means no security patches, no compatibility guarantee with current Laravel/PHP versions, no maintainer to escalate to, and effectively no peer review of the implementation. Your team becomes the sole maintainer of someone else's abandoned code.
- Any accuracy requirement beyond "as the crow flies." Real drive distance, ETA, or toll avoidance requires a routing vendor (Google Maps, Mapbox, HERE, OpenRouteService). Straight-line distance routinely under-reports real travel by 20–40% in dense or obstructed geographies — a product-visible error if you surface it to users or price on it.
- Scale. A per-row Haversine scan doesn't survive past a few thousand candidates. You need a bounding-box prefilter at minimum, then a spatial index (PostGIS, MySQL spatial types, Redis
GEO) — none of which this package provides.
- Anything touching geocoding, polygon/service-area containment, clustering, or map rendering. Out of scope entirely.
- Compliance-sensitive distance claims (delivery radius commitments, regulatory service areas). Unmaintained code with unknown test coverage is not the place to anchor a customer promise.
How to Pitch It (Stakeholders)
To executives: Do not adopt this as a dependency. It is an archived, single-purpose utility with no users, no maintainer, and no release in over two years — adopting it transfers maintenance risk to us in exchange for roughly a day of saved engineering. The underlying capability it represents, straight-line distance calculation, is a commodity we can own outright for about an hour of work. The strategic decision worth their attention is not this library; it is the geospatial stack behind it — a geocoding provider and a spatial index — which is where the real cost, vendor lock-in, and roadmap commitment live.
To engineering: Treat this as a reference implementation, not a dependency. Vendor the formula into a first-party Geo helper with our own tests, pin the coordinate-order and unit conventions explicitly, and wrap it behind an interface so we can swap in PostGIS or a routing vendor later without touching call sites. Add a bounding-box prefilter from day one if the candidate set can exceed a few thousand rows. Confirm Laravel/PHP compatibility before any copy-paste — the code predates current framework versions.
Recommended position: Reject as a dependency; harvest as a pattern. Net saving versus building is negligible, and the maintenance and compatibility exposure is not.