Download the PHP package jackardios/laravel-eloquent-spatial without Composer

Laravel Eloquent Spatial

Laravel package for working with spatial data types and functions in Eloquent.

This package is a fork of matanyadaev/laravel-eloquent-spatial, maintained by Jackardios.

Supported Databases

• MySQL 5.7 / 8.0 / 8.4
• MariaDB 10.11 / 11.4
• PostgreSQL 12–17 with PostGIS 3.4+

These are the versions that the tests run on.

Requirements

• PHP 8.3+
• Laravel 12.18+ / 13.x

For PHP 8.1 or 8.2, or Laravel 10, 11 or 12 before 12.18, use version 4.x.

Installation

Quick Start

1. Create a Migration

To restrict a column to one SRID, pass it to the column, for example $table->geometry('location', subtype: 'point', srid: 4326). MySQL 8 then rejects geometries with a different SRID.

2. Set Up Your Model

3. Work with Spatial Data

The geometries that a query compares must have the same SRID, so the examples use SRID 4326 throughout. Without an SRID, a geometry has the default SRID, 0 unless you change it.

Geometry Classes

All geometry classes support creating instances from various formats:

Each method reads only its own format: fromWkt() does not accept GeoJSON, and fromJson() does not accept WKT. Z and M coordinates are read and dropped. Factory::parse() detects which of these formats a string is in. It does not apply the default SRID: the SRID is the one in EWKT, EWKB or the MySQL format, and 0 for WKT and GeoJSON, while fromWkt(), fromJson() and fromArray() use the default SRID.

Available Geometry Types

Coordinate Validation

The Point class validates coordinates automatically. With SRID 0 (the default) or 4326, the coordinates are degrees:

Other SRIDs have their own units, so their ranges are not checked. With any SRID, the coordinates must be finite:

Spatial Query Scopes

The HasSpatial trait provides query scopes for spatial operations:

Distance Queries

The operator must be one of =, <, >, <=, >=, <> and !=, and the direction asc or desc in any case. Anything else throws InvalidArgumentException, because these arguments are written into the SQL. The alias of withDistance() and withDistanceSphere() is quoted as a column name.

Spatial Relationship Queries

BoundingBox

The BoundingBox class represents rectangular geographic bounds:

BoundingBox as Model Attribute

The geometry is stored with the default SRID unless the cast names one. On MySQL 8, a column with an SRID accepts only geometries with that SRID.

SRID Support

Spatial Reference Identifiers define coordinate systems:

Extending Geometry Classes

Using Macros

Custom Geometry Classes

Parsed and database values are then created as CustomPoint. A Point::class cast accepts it, and GeoJSON and WKB write it as a Point.

Long-running processes (Octane, queue workers)

The classes registered with EloquentSpatial::use*(), the default SRID and macros are static, so they are shared by all requests that a process handles. Set them once in the boot() method of a service provider, never per request.

Dirty Checks

The geometry and bounding box casts compare values themselves, so models detect changes correctly without the HasSpatial trait. A change of only the SRID or only the geometry type, such as a Point replaced by a MultiPoint with the same coordinates, is saved.

Limitations

• MariaDB does not support nested geometry collections: ST_GeomFromText() returns NULL for them, so such a value is saved as NULL.

• MySQL 8 reads WKT with a geographic SRID such as 4326 as latitude first. The package adds 'axis-order=long-lat' to the SQL it generates. If you assign a raw expression yourself, add it too:

• Geometries nested more than 64 levels deep are not read. Such values throw InvalidArgumentException, because reading them could crash PHP.
• Empty geometries other than GEOMETRYCOLLECTION EMPTY, such as POLYGON EMPTY, MULTIPOLYGON EMPTY, LINESTRING EMPTY and POINT EMPTY, are not read and throw InvalidArgumentException. PostGIS returns them from functions such as ST_Intersection() and ST_Difference(). A model whose geometry column holds such a value throws when the attribute is read, so store NULL instead.
• The rings of a polygon are not checked to be closed. POLYGON((0 0, 1 0, 1 1)) is read from WKT and GeoJSON and can be created from points; the database rejects it when it is saved.

API Reference

For complete API documentation, see API.md.

Upgrading

See UPGRADE.md for upgrade instructions from previous versions.

Development

License

MIT License. See LICENSE.md for details.