Geo Laravel Package

Product Decisions This Supports

• Location-aware feature scoping. This package supplies the geodetic primitives — coordinate value objects plus great-circle math (distance between points, bearing, destination point, radius/bounding-box derivation). That's enough to prototype and ship "nearest store," "within X km," "distance-sorted results," and delivery-zone eligibility without a paid geo API.
• Build vs. buy vs. adopt. It reframes the decision: you are not buying a geo platform, you are adopting ~a few hundred lines of MIT math. The real buy decisions remain geocoding, routing/ETA, and map rendering — this package does not attempt those, so it stays out of that budget line.
• Roadmap sequencing. Because it is tiny and framework-agnostic, it is a cheap way to validate demand for a geo feature (e.g., "sort marketplace listings by distance") before committing to PostGIS/MySQL spatial indexes, a tile provider contract, or a routing vendor.
• Pricing and eligibility logic. Straight-line distance plus bearing is often sufficient for tiered delivery fees, service-area checks, and "technician within radius" dispatch rules — decisions that would otherwise be blocked on a heavier GIS investment.
• Risk/effort tradeoff on custom math. The alternative to adopting it is hand-rolling haversine and edge-case handling (antimeridian, poles, unit confusion). Using a small, tested library reduces the chance of a subtle correctness bug in a customer-visible number.
• Not a fit for: geocoding addresses, turn-by-turn routing, polygon/geofence containment, or map tiles. If the roadmap item is "show a map" or "optimize a route," this package is at most a supporting dependency, not the feature.

When to Consider This Package

Consider it when all of the following hold:

• You need point-to-point geodetic math only: distance, bearing, midpoint, destination point, bounding-box/radius prefiltering.
• Your stack is plain PHP or Laravel and you want a Composer-installable, MIT-licensed dependency with no service contract, API key, rate limit, or per-request cost.
• Precision requirements are consumer-grade (store locators, delivery radius, distance sorting), not survey-grade or sub-meter.
• You can wrap it behind your own interface (e.g., a GeoDistance service or Laravel facade) so the underlying library is swappable.
• You will unit-test against known coordinate fixtures (equator, antimeridian, high latitude) as part of adoption.

Look elsewhere when:

• Maintenance risk matters more than size. 16 stars and no stated maintainer activity is a real signal; treat it as vendored code with a review obligation, not a supported platform.
• You need database-side spatial work — radius queries over 10⁵+ rows belong in PostGIS, MySQL SPATIAL, or a search index, not in PHP loops.
• You need geocoding, reverse geocoding, routing, isochrones, or map tiles — that is Google/Mapbox/Nominatim/OSRM territory.
• You need polygon, geofence, or geometry operations (intersections, containment) — reach for brick/geo, GEOS bindings, or a spatial database instead.
• You need datum transformations or ellipsoidal (Vincenty/Karney) accuracy — verify the library's model first; great-circle math may not meet your tolerance.

How to Pitch It (Stakeholders)

To executives: This is a small, free, MIT-licensed PHP library that gives us the coordinate math behind location features — distance, direction, and "within X kilometers" filtering. It lets us ship a first version of a distance-based feature (store locator, delivery radius, distance-sorted results) in days rather than weeks, with no vendor contract, no API keys, no per-request fees, and no data leaving our infrastructure. The tradeoff is community size: it has modest adoption, so we'll isolate it behind our own internal interface and cover it with tests — meaning we get the speed benefit now and keep the option to replace it later at low cost.

To engineering: Pure PHP, framework-agnostic, Composer-installable, MIT. Expected surface is small — coordinate objects plus great-circle calculations. Integration is a thin adapter: wrap it in a single service/facade, forbid direct usage elsewhere, and add fixture tests around the antimeridian and high latitudes. Do not use it for spatial queries at scale (push those to the database) or for any geometry/polygon work. Budget roughly half a day for adoption plus a documented exit path if the package goes stale.