Laravel Eloquent Spatial Laravel Package

Product Decisions This Supports

• Geo-feature scoping without a new platform. If a roadmap item is "find stores/drivers/listings near me," "show what's in my delivery zone," or "rank results by distance," this package turns that from a multi-sprint data-layer project into a schema addition plus a handful of Eloquent scopes. It supports deciding to ship a geo MVP now rather than waiting on a search-infrastructure bet.
• Build vs. buy for geo. Presents a credible third option between "write raw ST_Distance SQL ourselves" and "buy a managed geo/search vendor." When geo is a supporting capability rather than the product's core ranking engine, this is the cheap path: no new vendor, no dual-write sync, no per-query bill.
• Source-of-truth architecture. Keeps spatial data in the same relational database as the rest of the domain. That means no synchronization job between Postgres and an external index, no consistency drift, and one backup/access-control story. A PM can use this to argue against prematurely introducing a second datastore.
• Concrete use cases it unlocks: proximity search and distance sorting, radius/service-area eligibility, polygon containment for delivery zones and geo-fences, point storage for assets or check-ins, and simple density/heatmap reporting.
• Roadmap sequencing. Adopting it now defers investment in Elasticsearch/Algolia/Mapbox-class infrastructure until volume or relevance requirements actually justify it, and the exit cost stays low because the data already lives where it belongs.
• Effort signal for prioritization. Roughly: one migration to add spatial columns and indexes, model casts, and query scopes — days, not weeks. That changes the cost side of the business case for small geo features that were previously "not worth it."

When to Consider This Package

Consider it when:

• The application is Laravel with Eloquent as the data layer, and the team is already comfortable writing migrations.
• Production runs PostgreSQL (with PostGIS) or MySQL 8+ — the package's value depends entirely on the database's native spatial support. Confirm the exact dialect and version matrix before committing.
• Geo is a supporting feature: locators, radius filtering, zone checks, distance sorting. Query volumes in the thousands-to-low-millions of rows with proper spatial indexes are the sweet spot.
• You want typed model attributes for points/polygons and reusable query scopes instead of hand-rolled SQL scattered across controllers.
• You want to avoid a vendor contract, per-request geo pricing, and a second data store.

Look elsewhere when:

• You need geocoding, reverse geocoding, routing/ETA, isochrones, or map tiles. This package stores and queries geometry; it does not resolve addresses or compute routes. Budget Mapbox, Google, or OSRM alongside it.
• Geo relevance is core to search at scale — combined full-text-plus-distance ranking over large corpora belongs in Elasticsearch/OpenSearch/Meilisearch.
• The database is SQLite-only in production, or the team cannot add spatial columns and indexes to existing tables.
• You require vendor SLAs, security review, or a support contract. With ~400 stars and a single-maintainer profile, procurement-heavy or regulated environments may reject it on dependency-risk grounds alone.
• Workloads are genuinely 3D, raster, or heavy geospatial analytics — use PostGIS directly or a dedicated GIS stack.

Practical adoption guardrails: pin the version, verify the license and release cadence hold, wrap spatial access behind your own repository/service layer so the package is swappable, and load-test the actual query patterns against realistic row counts before committing.

How to Pitch It (Stakeholders)

For executives: This is a small, free (MIT), open-source library that lets us ship location features — "near me" search, delivery-zone checks, distance ranking — using the database we already run. No new vendor, no new contract, no per-query fees, and no second copy of our data to keep in sync. The integration cost is measured in days. The main caveat is that it is community-maintained with a modest user base, so we should treat it as a replaceable component rather than a foundation: we isolate it behind a thin internal layer, which keeps our exit cost near zero if we later outgrow it or it goes stale.

For engineering: It provides Eloquent casts and query scopes over native spatial types, which removes bespoke ST_* SQL from our application code and gives us typed geometry attributes, migration support, and composable distance/containment scopes. It is not a geo platform — it does no geocoding or routing, and it inherits every limitation of the underlying database's spatial engine, including index strategy and dialect differences. Adopt it behind an interface: pin the version, keep spatial columns and indexes in our own migrations, and benchmark the real query patterns on production-shaped data before rollout. If the maintainer goes quiet or our requirements shift toward relevance-ranked geo search, we swap the implementation without touching domain code.

Bottom line: a low-risk, high-leverage enabler for supporting geo features in a Laravel/Postgres or MySQL stack — approved for scoped adoption with an isolation layer, not for cases where location is the product.