- How do I install and set up malhal/laravel-geographical in a Laravel app?
- Install it with composer require malhal/laravel-geographical. The service provider is auto-discovered, so no manual registration is needed on modern Laravel. Then add the latitude and longitude columns to your migration and add the trait's use statement to each Eloquent model that should be location-aware. A working proof of concept typically takes under a day.
- How do I add latitude and longitude columns with the package's migration macro?
- The package registers a Blueprint macro, so you can call it as an extra column type inside Schema::create or Schema::table. It adds the latitude and longitude columns for you instead of writing two decimal columns by hand. Check the generated column precision against your geocoding source before you backfill data. Run the migration as normal with php artisan migrate.
- How do I filter Eloquent records within a radius using this package?
- Add the trait to your model and chain the distance scope with a maximum distance argument. The scope compiles raw SQL trigonometry into the WHERE clause, so results come back filtered by Haversine distance rather than by a simple bounding box. Confirm whether your version expects kilometers or miles, because unit mismatches are the most common source of wrong-looking results. Combine the scope with your own where clauses and pagination as usual.
- How do I order results by distance and access the computed distance value?
- The package exposes a distance scope for ordering and a computed distance accessor on the model. Call the scope to order by proximity, then read the accessor on each returned model; add it to $appends if you need it in JSON responses. Remember the accessor depends on the SELECT expression being present, so a plain find() will not have a distance. Also watch for unstable ordering when several rows share the same distance, and add a tiebreaker like id.
- Which databases does the Haversine scope support, and will it work with SQLite in tests?
- The distance math uses raw SQL functions such as acos, cos, radians, and sin, which are available in MySQL, MariaDB, and PostgreSQL. SQLite builds used for in-memory test suites do not always compile those math functions in, so CI can fail in ways that only appear on the test runner. Verify your actual driver in the POC and, if needed, run distance tests against a real MySQL or Postgres connection. Keep non-distance tests on SQLite so the suite stays fast.
- Which Laravel and PHP versions does malhal/laravel-geographical support?
- Support is expressed as illuminate/database version constraints in the package's composer.json, so check Packagist for the current matrix before planning an upgrade. Because the package is a thin trait plus a Blueprint macro rather than a framework extension, upgrades usually carry little friction. Still pin the version in composer.json and re-run your geo tests after each Laravel minor bump. There is a May 2025 release line, so confirm it covers your current and next framework version.
- Is this package fast enough for large tables, and can the distance query use an index?
- A computed trig expression in WHERE or ORDER BY cannot use a normal B-tree index, so every distance query is effectively a full scan with per-row math. That is fine at thousands of rows, uncomfortable at hundreds of thousands, and untenable at millions. Add a cheap bounding-box pre-filter with BETWEEN on latitude and longitude before the distance scope so the database can use plain indexes first. If radius search becomes a core feature at volume, move it to PostGIS or a search engine with native geo support.
- What happens if a record has null, zero, or invalid coordinates?
- Missing or malformed coordinates are the most likely source of defects: a null latitude makes the trig expression null, which can silently drop the row from a radius filter or return an unexpected value from the accessor. Zero coordinates are also ambiguous, because 0,0 is a real point in the Atlantic but often a placeholder for unknown. Validate and backfill coordinates before you rely on the results, and decide explicitly whether records without coordinates should be excluded. Wrap the scope with a whereNotNull on both columns if you need deterministic behaviour.
- Is malhal/laravel-geographical a good fit for polygons, route geometry, or PostGIS-style spatial queries?
- No. The package is a convenience layer over two numeric columns and Haversine arithmetic, not a geospatial engine; it does not do polygon containment, route geometry, or geography types. If those are on your roadmap, use PostGIS with a geography column, or delegate radius search to Meilisearch, Algolia, or Elasticsearch, which handle geo queries natively. This package is best for location as a secondary attribute on stores, users, listings, or assets.
- Is the package still maintained, and what is the fallback if it is abandoned?
- It is a small, MIT-licensed package with a single maintainer, so bus factor is real, but the surface area is tiny: a Blueprint macro and a trait with a handful of SQL expressions. That makes fork-and-vendor a genuine fallback if the package stalls. Pin the version, keep your own tests around the distance scope, and you can copy the trait into your app in an afternoon if needed.