limenet / laravel-mysql-spatial
MySQL spatial data types extension for Laravel.
Installs: 6 484
Dependents: 0
Suggesters: 0
Security: 0
Stars: 8
Watchers: 3
Forks: 312
Open Issues: 2
Requires
- php: ^8.1
- ext-json: *
- ext-pdo: *
- doctrine/dbal: ^3.5
- geo-io/wkb-parser: ^1.0
- illuminate/contracts: ^10.0
- illuminate/database: ^10.0
- jmikola/geojson: ^1.0
Requires (Dev)
- driftingly/rector-laravel: ^0.21.0
- laravel/browser-kit-testing: ^7.0
- laravel/laravel: ^10.2.4
- laravel/pint: ^1.10.3
- mockery/mockery: ^1.6.2
- nunomaduro/collision: ^7.7.0
- nunomaduro/larastan: ^2.6.3
- orchestra/testbench: ^8.5.9
- phpstan/extension-installer: ^1.3.1
- phpstan/phpstan-deprecation-rules: ^1.1.3
- phpstan/phpstan-phpunit: ^1.3.13
- phpunit/phpunit: ^10.2.3
- rector/rector: ^0.17.2
- dev-master
- 10.0.0
- v4.x-dev
- 4.0.0
- 3.0.0
- 2.2.3
- 2.2.2
- 2.2.1
- 2.2.0
- 2.1.3
- 2.1.2
- 2.1.1
- 2.1.0
- 2.0.3
- 2.0.2
- 2.0.1
- 2.0.0
- 1.3.3
- 1.3.2
- 1.3.1
- 1.3.0
- 1.2.0
- 1.1.4
- 1.1.3
- 1.1.2
- 1.1.1
- 1.1.0
- dev-mysql-5.6 / 1.0.x-dev
- 1.0.0
- dev-laravel-11
- dev-laravel-10
- dev-fix/geometry-collection
- dev-feature/geojson
- dev-laravel-8
- dev-srid
- dev-fix/locale-polyfill
- dev-test-issue-26
- dev-builder-as-trait
This package is auto-updated.
Last update: 2024-10-10 09:10:13 UTC
README
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.
This package is a fork of https://github.com/grimzy/laravel-mysql-spatial and virtually all code was written by the contributors to that repo. Thank you!
This package also works with MariaDB. Please refer to the MySQL/MariaDB Spatial Support Matrix for compatibility.
Installation
Add the package using composer:
$ composer require limenet/laravel-mysql-spatial
If you need support for older versions, please consider using the package grimzy/laravel-mysql-spatial
instead.
Migration from grimzy/laravel-mysql-spatial
- Run
composer remove grimzy/laravel-mysql-spatial
- Run
composer require limenet/laravel-mysql-spatial
- Replace
Grimzy\
withLimenet\
throughout your codebase (most likely, this only affectsuse
statements)
Quickstart
Create a migration
From the command line:
php artisan make:migration create_places_table
Then edit the migration you just created by adding at least one spatial data field.
use Illuminate\Database\Migrations\Migration; use Illuminate\Database\Schema\Blueprint; class CreatePlacesTable extends Migration { public function up(): void { Schema::create('places', function(Blueprint $table) { $table->increments('id'); $table->string('name')->unique(); // Add a Point spatial data field named location $table->point('location')->nullable(); // Add a Polygon spatial data field named area $table->polygon('area')->nullable(); $table->timestamps(); }); // Or create the spatial fields with an SRID (e.g. 4326 WGS84 spheroid) // Schema::create('places', function(Blueprint $table) // { // $table->increments('id'); // $table->string('name')->unique(); // // Add a Point spatial data field named location with SRID 4326 // $table->point('location', 4326)->nullable(); // // Add a Polygon spatial data field named area with SRID 4326 // $table->polygon('area', 4326)->nullable(); // $table->timestamps(); // }); } public function down(): void { Schema::drop('places'); } }
Run the migration:
php artisan migrate
Create a model
From the command line:
php artisan make:model Place
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:
namespace App; use Illuminate\Database\Eloquent\Model; use Limenet\LaravelMysqlSpatial\Eloquent\SpatialTrait; /** * @property \Limenet\LaravelMysqlSpatial\Types\Point $location * @property \Limenet\LaravelMysqlSpatial\Types\Polygon $area */ class Place extends Model { use SpatialTrait; protected $fillable = [ 'name' ]; protected $spatialFields = [ 'location', 'area' ]; }
Saving a model
use Limenet\LaravelMysqlSpatial\Types\Point; use Limenet\LaravelMysqlSpatial\Types\Polygon; use Limenet\LaravelMysqlSpatial\Types\LineString; $place1 = new Place(); $place1->name = 'Empire State Building'; // saving a point $place1->location = new Point(40.7484404, -73.9878441); // (lat, lng) $place1->save(); // saving a polygon $place1->area = new Polygon([new LineString([ new Point(40.74894149554006, -73.98615270853043), new Point(40.74848633046773, -73.98648262023926), new Point(40.747925497790725, -73.9851602911949), new Point(40.74837050671544, -73.98482501506805), new Point(40.74894149554006, -73.98615270853043) ])]); $place1->save();
Or if your database fields were created with a specific SRID:
use Limenet\LaravelMysqlSpatial\Types\Point; use Limenet\LaravelMysqlSpatial\Types\Polygon; use Limenet\LaravelMysqlSpatial\Types\LineString; $place1 = new Place(); $place1->name = 'Empire State Building'; // saving a point with SRID 4326 (WGS84 spheroid) $place1->location = new Point(40.7484404, -73.9878441, 4326); // (lat, lng, srid) $place1->save(); // saving a polygon with SRID 4326 (WGS84 spheroid) $place1->area = new Polygon([new LineString([ new Point(40.74894149554006, -73.98615270853043), new Point(40.74848633046773, -73.98648262023926), new Point(40.747925497790725, -73.9851602911949), new Point(40.74837050671544, -73.98482501506805), new Point(40.74894149554006, -73.98615270853043) ])], 4326); $place1->save();
Note: When saving collection Geometries (
LineString
,Polygon
,MultiPoint
,MultiLineString
, andGeometryCollection
), 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 thePolygon
and use the default for theLineString
and thePoint
objects.
Retrieving a model
$place2 = Place::first(); $lat = $place2->location->getLat(); // 40.7484404 $lng = $place2->location->getLng(); // -73.9878441
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 Limenet\LaravelMysqlSpatial\Eloquent\SpatialTrait
trait and define a protected
property $spatialFields
as an array of MySQL Spatial Data Type column names (example in Quickstart).
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:
$polygon = $multipolygon[10]; // ArrayAccess // IteratorAggregate for($polygon as $i => $linestring) { echo (string) $linestring; }
Helpers
From/To Well Known Text (WKT)
// fromWKT($wkt, $srid = 0) $point = Point::fromWKT('POINT(2 1)'); $point->toWKT(); // POINT(2 1) $polygon = Polygon::fromWKT('POLYGON((0 0,4 0,4 4,0 4,0 0),(1 1, 2 1, 2 2, 1 2,1 1))'); $polygon->toWKT(); // POLYGON((0 0,4 0,4 4,0 4,0 0),(1 1, 2 1, 2 2, 1 2,1 1))
From/To String
// fromString($wkt, $srid = 0) $point = new Point(1, 2); // lat, lng (string)$point // lng, lat: 2 1 $polygon = Polygon::fromString('(0 0,4 0,4 4,0 4,0 0),(1 1, 2 1, 2 2, 1 2,1 1)'); (string)$polygon; // (0 0,4 0,4 4,0 4,0 0),(1 1, 2 1, 2 2, 1 2,1 1)
From/To JSON (GeoJSON)
The Geometry classes implement JsonSerializable
and Illuminate\Contracts\Support\Jsonable
to help serialize into GeoJSON:
$point = new Point(40.7484404, -73.9878441); json_encode($point); // or $point->toJson(); // { // "type": "Feature", // "properties": {}, // "geometry": { // "type": "Point", // "coordinates": [ // -73.9878441, // 40.7484404 // ] // } // }
To deserialize a GeoJSON string into a Geometry class, you can use Geometry::fromJson($json_string)
:
$location = Geometry::fromJson('{"type":"Point","coordinates":[3.4,1.2]}'); $location instanceof Point::class; // true $location->getLat(); // 1.2 $location->getLng()); // 3.4
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, 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 theSPATIAL
keyword. Columns in spatial indexes must be declaredNOT 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:
php artisan make:migration update_places_table
Then edit the migration file that you just created:
use Illuminate\Database\Migrations\Migration; use Illuminate\Database\Schema\Blueprint; use Illuminate\Support\Facades\Schema; class UpdatePlacesTable extends Migration { /** * Run the migrations. * * @return void */ public function up() { // MySQL < 5.7.5: table has to be MyISAM // \DB::statement('ALTER TABLE places ENGINE = MyISAM'); Schema::table('places', function (Blueprint $table) { // Make sure point is not nullable $table->point('location')->change(); // Add a spatial index on the location field $table->spatialIndex('location'); }); } /** * Reverse the migrations. * * @return void */ public function down() { Schema::table('places', function (Blueprint $table) { $table->dropSpatialIndex(['location']); // either an array of column names or the index name }); // \DB::statement('ALTER TABLE places ENGINE = InnoDB'); Schema::table('places', function (Blueprint $table) { $table->point('location')->nullable()->change(); }); } }
Tests
$ composer test
Integration tests require a running MySQL database. If you have Docker installed, you can start easily start one:
$ make start_db # starts MySQL 8.0 # or $ make start_db V=5.7 # starts MySQL 5.7
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.