Download the PHP package scaffold-digital/laravel-mysql-spatial without Composer

Laravel MySQL Spatial extension

Laravel package to easily work with MySQL Spatial Data Types and MySQL Spatial Functions.

Please check the documentation for your MySQL version. MySQL's Extension for Spatial Data was added in MySQL 5.5 but many Spatial Functions were changed in 5.6 and 5.7.

Versions

• 5.x.x: MySQL 5.7 and 8.0 (Laravel 8)
• 6.x.x: MySQL 8.0 (Laravel 9)
• 7.x.x: MySQL 8.0 (Laravel 10)
• 8.x.x: MySQL 8.0 (Laravel 11)

This package also works with MariaDB. Please refer to the MySQL/MariaDB Spatial Support Matrix for compatibility.

Installation

Add the package using composer:

Quick start

Create a migration

From the command line:

Then edit the migration you just created by adding at least one spatial data field:

Run the migration:

Create a model

From the command line:

Then edit the model you just created. It must use the SpatialTrait and define an array called $spatialFields with the name of the MySQL Spatial Data field(s) created in the migration:

Saving a model

Or if your database fields were created with a specific SRID:

Note: When saving collection Geometries (LineString, Polygon, MultiPoint, MultiLineString, and GeometryCollection), only the top-most geometry should have an SRID set in the constructor.

In the example above, when creating a new Polygon(), we only set the SRID on the Polygon and use the default for the LineString and the Point objects.

Retrieving a model

Geometry classes

Available Geometry classes

Check out the Class diagram.

Using Geometry classes

In order for your Eloquent Model to handle the Geometry classes, it must use the ScaffoldDigital\LaravelMysqlSpatial\Eloquent\SpatialTrait trait and define a protected property $spatialFields as an array of MySQL Spatial Data Type column names (example in Quick start).

IteratorAggregate and ArrayAccess

The collection Geometries (LineString, Polygon, MultiPoint, MultiLineString, and GeometryCollection) implement IteratorAggregate and ArrayAccess; making it easy to perform Iterator and Array operations. For example:

Helpers

From/To Well Known Text (WKT)

From/To String

From/To JSON (GeoJSON)

The Geometry classes implement JsonSerializable and Illuminate\Contracts\Support\Jsonable to help serialize into GeoJSON:

To deserialize a GeoJSON string into a Geometry class, you can use Geometry::fromJson($json_string) :

Scopes: Spatial analysis functions

Spatial analysis functions are implemented using Eloquent Local Scopes.

Available scopes:

• distance($geometryColumn, $geometry, $distance)
• distanceExcludingSelf($geometryColumn, $geometry, $distance)
• distanceSphere($geometryColumn, $geometry, $distance)
• distanceSphereExcludingSelf($geometryColumn, $geometry, $distance)
• comparison($geometryColumn, $geometry, $relationship)
• within($geometryColumn, $polygon)
• crosses($geometryColumn, $geometry)
• contains($geometryColumn, $geometry)
• disjoint($geometryColumn, $geometry)
• equals($geometryColumn, $geometry)
• intersects($geometryColumn, $geometry)
• overlaps($geometryColumn, $geometry)
• doesTouch($geometryColumn, $geometry)
• orderBySpatial($geometryColumn, $geometry, $orderFunction, $direction = 'asc')
• orderByDistance($geometryColumn, $geometry, $direction = 'asc')
• orderByDistanceSphere($geometryColumn, $geometry, $direction = 'asc')

Note that behavior and availability of MySQL spatial analysis functions differs in each MySQL version (cf. documentation).

Columns

Available MySQL Spatial Types migration blueprints:

• $table->geometry(string $column_name, ?string $subtype = null, int $srid = 0)
• $table->point(string $column_name, int $srid = 0)
• $table->lineString(string $column_name, int $srid = 0)
• $table->polygon(string $column_name, int $srid = 0)
• $table->multiPoint(string $column_name, int $srid = 0)
• $table->multiLineString(string $column_name, int $srid = 0)
• $table->multiPolygon(string $column_name, int $srid = 0)
• $table->geometryCollection(string $column_name, int $srid = 0)

Spatial indexes

You can add or drop spatial indexes in your migrations with the spatialIndex and dropSpatialIndex blueprints.

• $table->spatialIndex('column_name')
• $table->dropSpatialIndex(['column_name']) or $table->dropSpatialIndex('index_name')

Note about spatial indexes from the MySQL documentation:

For MyISAM and (as of MySQL 5.7.5) InnoDB tables, MySQL can create spatial indexes using syntax similar to that for creating regular indexes, but using the SPATIAL keyword. Columns in spatial indexes must be declared NOT NULL.

Also please read this important note regarding Index Lengths in the Laravel 5.6 documentation.

For example, as a follow up to the Quickstart; from the command line, generate a new migration:

Then edit the migration file that you just created:

Tests

Integration tests require a running MySQL database. If you have Docker installed, you can start easily start one:

Contributing

Recommendations and pull request are most welcome! Pull requests with tests are the best! There are still a lot of MySQL spatial functions to implement or creative ways to use spatial functions.

Credits

Originally inspired from:

• njbarrett's Laravel postgis package
• grimzy's laravel-mysql-spatial package