Interface Laravel Package

Product Decisions This Supports

• Build vs. buy for geospatial primitives. This package is a contracts layer, not an implementation. Adopting it is a bet that defining your geometry vocabulary (points, coordinates, bounding boxes, geometry enums) is cheap, and that the actual math/storage belongs to a swappable backend (PostGIS, MySQL spatial, MongoDB geo, Elasticsearch, GeoJSON). That is usually the right bet — it keeps your domain model portable.
• Feature roadmap it unlocks (or de-risks):
  • Store/asset locator with proximity search ("nearest 5 within 10 km").
  • Delivery/service-area polygons and geofencing rules.
  • Address/place geotagging on any entity (customers, listings, events).
  • Route and itinerary primitives, multi-stop planning.
  • Territory/region assignment, boundary checks, "is this address in zone X?"
• Multi-vendor and platform integrations. If you ingest geometry from several providers (Google, Mapbox, a warehouse, a partner API), typed value objects give you a single normalization point. That reduces the surface area where provider quirks leak into product logic — a real maintenance cost center.
• Domain modeling decision. Value objects (immutable, self-validating) versus loose arrays of lat/lng floats. Choosing this now avoids a painful retrofit when you inevitably add a second geo feature. Most teams under-invest here and pay for it later in duplicated validation and inconsistent coordinate handling.
• Roadmap sequencing input. Because this is interface-only, it belongs early — it's a foundation dependency, not a feature. If it's in scope, schedule it before the first geo feature ships, not after. Shipping a locator against raw arrays and retrofitting contracts later means rewriting query and DTO layers.

When to Consider This Package

Adopt when:

• You expect more than one geo feature across the roadmap. One feature rarely justifies an abstraction layer; three do.
• You need to decouple product domain logic from a specific geo library or database vendor — e.g., prototypes on MySQL, production on PostGIS, or a migration on the horizon.
• Your team already values typed DTOs and immutable value objects, and you want a shared vocabulary rather than each squad inventing its own Location class.
• You are assembling a modular or multi-tenant system where geo concepts cross package boundaries and need a stable contract.
• You want a thin, MIT-licensed, near-zero-runtime-cost dependency — interfaces and enums, no heavy algorithms.

Look elsewhere when:

• You need actual computation. This package defines contracts, not distance, area, intersection, or spatial indexing. Pair it with a real implementation (a database with spatial support, phpgeo-style geometry math, or a geocoder) or you'll be writing the math yourself.
• You have exactly one simple geo need. A store locator against PostGIS queries is fine with plain value objects. Adding an abstraction for a single use case is overhead with no payoff.
• Frontend-only mapping. If the map, routing, and spatial logic live in Mapbox/Google Maps on the client, this is not the layer you're solving for.
• Maintenance risk is unacceptable. Be honest about the signals here: unknown repository, 62 stars, low confidence score. Verify the actual commit history, PHP version support, and whether the sibling implementation packages are active. An abandoned contracts package is comparatively low-risk (interfaces are stable and you can vendor a fork under MIT), but an abandoned implementation behind it is not. Confirm the implementation path exists before committing the roadmap to it.
• You need compliance-grade geometry (audited geospatial calculations, regulated logistics). Validate the whole stack, not just this layer.

How to Pitch It (Stakeholders)

Executive summary. This is a small, MIT-licensed PHP dependency that standardizes how our code represents geographic data — points, coordinates, areas — and how features talk to map and location services. It is infrastructure, not a user-facing feature. Its value is optionality: it lets us add location features (store locators, delivery zones, geotagging) on a consistent foundation and switch underlying mapping or database providers without rewriting product logic. Cost is negligible; the real investment is the engineering discipline it implies.

For engineering. Interfaces, enums, and immutable value objects only — no algorithms, no I/O, no framework coupling. It gives us a shared contract so geo logic sits in one place rather than five, and so we can back it with PostGIS, a geocoder, or a third-party API and swap later. Adopt it as the vocabulary layer, and pair it with a concrete implementation. Caveats to validate before we commit: the upstream repository and maintenance cadence are not clearly established and the project is small. Because it's interfaces only with an MIT license, the failure mode is contained — we can fork or vendor it if needed — but we should confirm the implementation packages we'll depend on are actively maintained, and pin versions.

For the business. The pitch is speed and reversibility. Location features are a recurring ask, and each one built ad hoc adds custom code we can't easily reuse or repoint at a new vendor. Standardizing now is cheap insurance against a costly migration later. The risk is supplier maturity, which we mitigate by keeping the dependency thin and swappable, and by validating the ecosystem before roadmap commitments.