Laravel Eloquent Spatial Laravel Package

Technical Evaluation

Architecture fit

• The package is an additive, idiomatic Laravel library: it registers a service provider, extends the schema builder with spatial column types (geometry, point, polygon, geography, etc.), adds Eloquent casts that translate between WKT/WKB/GeoJSON and PHP value objects, and exposes query-builder macros for spatial predicates (within, intersects, distance, orderByDistance).
• It does not impose an architecture, replace Eloquent, or require a base model. That makes it a low-coupling fit for any existing Laravel domain model — you can adopt it for a single bounded context (e.g., store locations, delivery zones) without touching the rest of the codebase.
• The real architectural coupling is not to the package but to the database: the design assumes a spatially-enabled engine (PostGIS, MySQL 8, SpatiaLite). That is the decision that carries weight, not the PHP dependency.

Integration feasibility

• Trivially installable (composer require + auto-discovery). Integration effort concentrates in two places: migrations (converting existing lat/lng decimals or raw WKT string columns into real geometry columns) and serialization (deciding whether APIs emit GeoJSON, WKT, or coordinates).
• Driver parity is the main unknown. PostGIS is the most complete target; MySQL 8 works but imposes SRID constraints (spatial columns are SRID-typed, and spatial indexes require a non-null SRID); SQLite is realistically a test-only target via SpatiaLite. Behavior will differ across drivers for SRID handling, geography vs geometry semantics, and function availability.
• Requires a PHP-side geometry value object library (commonly brick/geo) — worth confirming which one the package version expects, since that becomes a second dependency to govern.

Technical risk

• Maintainer concentration: 422 stars and a single-maintainer profile is typical of high-quality but fragile OSS. Laravel major-version drift (new schema/query-builder internals) is the most likely breakage vector.
• Driver divergence: code that passes on SQLite/SpatiaLite in CI can fail or silently return wrong results on MySQL 8 vs PostGIS. Silent wrongness (SRID mismatch) is worse than a hard failure.
• Query performance: the macros generate correct SQL but do not guarantee index usage. Distance filtering without a bounding-box prefilter is a common production footgun.
• Migration reversibility: dropping spatial columns and their indexes is uneven across drivers; rollbacks need explicit testing.
• Maturity signals: the composite score and opportunity rating are modest relative to star count, which is consistent with a niche, competent utility rather than a broadly strategic dependency. Treat it as a tactical enabler, not a platform bet.

Key questions

1. What is the production database, and is it already spatially enabled (PostGIS extension installed, MySQL 8 with SRID-typed columns)? Who owns that extension lifecycle?
2. Which SRID is canonical (4326 for lat/lng, 3857 for web mapping), and is there an existing convention to conform to?
3. Geometry or geography? (Distance semantics differ: degrees vs meters.)
4. What are the query patterns — point-in-polygon lookups, radius search, nearest-neighbor ordering? Each has a different indexing strategy.
5. What is the GeoJSON/serialization contract expected by API consumers, and does it need to be stable across the migration?
6. Can we accept a single-maintainer dependency, and what is the fork/patch contingency if it stalls?

Integration Approach

Stack fit

• Laravel + Eloquent with either PostGIS (recommended for function coverage and index quality) or MySQL 8. No change to the app's service layer, queueing, or auth model.
• Fits cleanly behind a repository or a model trait: encapsulate spatial casts and query scopes in one trait so the package is referenced in a small number of files. That keeps swap-out cost low if the dependency is later replaced or forked.

Migration path

• Phase 0 — inventory. Catalogue every place geography is stored today: decimal lat/lng pairs, raw WKT/text columns, GeoJSON blobs in JSON columns, or external geocoding service calls made at read time.
• Phase 1 — additive schema. Add spatial columns alongside existing ones; backfill with driver-native functions (e.g., ST_GeomFromText/ST_SetSRID, or ST_PointFromText on MySQL with SRID). Keep old columns readable and populated.
• Phase 2 — dual-read. Introduce the casts and scopes; run new spatial queries in shadow mode and compare results against legacy paths for a sample of real traffic.
• Phase 3 — cut over reads, then writes, then drop the legacy columns and their now-redundant indexes in a separate, reversible migration.

Compatibility

• Pin the package version explicitly and record the Laravel version it was validated against. Add a CI matrix job against the real production engine (not just SQLite) for the spatial test suite — this is the single highest-value guardrail.
• Verify extension availability in every environment (local, CI, staging, prod) before merging the first spatial migration; a missing PostGIS extension turns a deploy into an outage.

Sequencing

1. Prove out on one bounded domain with the least ambiguity (e.g., store/asset locations).
2. Establish the SRID and geometry-vs-geography convention and document it.
3. Build the shared model trait + spatial query scopes.
4. Define and freeze the API serialization contract (GeoJSON preferred).
5. Roll out to remaining domains; retire legacy columns last.

Operational Impact

Maintenance

• Low ongoing code maintenance but non-zero dependency maintenance: budget a recurring review at each Laravel major release and each PHP minor. Keep the package behind a version constraint and maintain a fork-ready posture (small surface area, one trait, no deep patching).
• The brick/geo (or equivalent) value-object dependency must be tracked in parallel.

Support

• Community-only support, no vendor SLA. Assign an internal owner (a backend engineer with spatial literacy) as the escalation point. Maintain an internal runbook covering SRID conventions, supported drivers, and known divergences.

Scaling

• Correctness at scale depends almost entirely on indexing, not on the package: GiST indexes on PostGIS, SPATIAL INDEX on MySQL with an explicit SRID.
• Mandate a bounding-box prefilter (ST_Within against an envelope, or && operators) before any ST_Distance filter or ORDER BY distance; unbounded distance sorts are the classic full-table-scan incident.
• PostGIS scales further for complex geometry operations (buffers, unions, topology). MySQL 8 is adequate for point and simple polygon work but will hit function and precision ceilings sooner.

Failure modes

• Missing spatial extension in a new environment → migration/deploy failure. Mitigate with pre-deploy environment checks.
• SRID mismatch → silently incorrect distances and containment results. Mitigate with a single enforced convention and assertion tests.
• Index not used → latency spike under load with no obvious error. Mitigate with query plans reviewed in CI for the hot spatial queries.
• Driver divergence between CI (SQLite) and production (PostGIS/MySQL) → green builds, broken prod. Mitigate with a real-engine CI job.
• Dependency stall against a future Laravel major → blocked upgrade. Mitigate by keeping the integration surface to one trait and a handful of casts.
• Irreversible migrations → orphaned indexes or dropped data on rollback. Mitigate by splitting schema changes from cleanup.

Ramp-up

• Engineer ramp-up is the dominant cost, not the package: SRID semantics, geometry vs geography, WKT/GeoJSON, index types, and query-plan reading are new skills for most Laravel developers. Plan roughly 2–4 weeks of effective ramp for the team, front-loaded with a spike and a written internal playbook.
• TPM actions: fund the spike, require the real-engine CI matrix, set the SRID/serialization conventions as explicit decisions with owners, and gate rollout on the shadow-read comparison rather than on code review alone.