PHPackages                             kreateyou/grimzy-octobercms-mysql-spatial - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. kreateyou/grimzy-octobercms-mysql-spatial

ActiveLibrary

kreateyou/grimzy-octobercms-mysql-spatial
=========================================

MySQL spatial data types extension for Laravel.

v2.1.4(6y ago)117MITPHPPHP >=5.5

Since Jun 4Pushed 6y agoCompare

[ Source](https://github.com/Kreateyou/laravel-mysql-spatial)[ Packagist](https://packagist.org/packages/kreateyou/grimzy-octobercms-mysql-spatial)[ RSS](/packages/kreateyou-grimzy-octobercms-mysql-spatial/feed)WikiDiscussions master Synced 2mo ago

READMEChangelog (1)Dependencies (9)Versions (21)Used By (0)

Laravel MySQL Spatial extension
===============================

[](#laravel-mysql-spatial-extension)

[![Build Status](https://camo.githubusercontent.com/2779e6e69c69320c8e3c4194b007e7e055f3f4cecd4bd214d139777c9477ba18/68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f6772696d7a792f6c61726176656c2d6d7973716c2d7370617469616c2e7376673f7374796c653d666c61742d737175617265)](https://travis-ci.org/grimzy/laravel-mysql-spatial)[![Code Climate](https://camo.githubusercontent.com/5f94b18bbdeaad49f5c36318a5226abc1d86d521d945394947e52fb570b46fb7/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636c696d6174652f6d61696e7461696e6162696c6974792f6772696d7a792f6c61726176656c2d6d7973716c2d7370617469616c2e7376673f7374796c653d666c61742d737175617265)](https://codeclimate.com/github/grimzy/laravel-mysql-spatial/maintainability)[![Code Climate](https://camo.githubusercontent.com/8f02d49eda676772209f4c9f55cbf1c4e5ac0a82d3d2173bda903eb81da6ddcd/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636c696d6174652f632f6772696d7a792f6c61726176656c2d6d7973716c2d7370617469616c2e7376673f7374796c653d666c61742d73717561726526636f6c6f72423d344243413241)](https://codeclimate.com/github/grimzy/laravel-mysql-spatial/test_coverage) [![Packagist](https://camo.githubusercontent.com/f45c7720c76f541083b28884bd78620436cbd62798b03297f3d2db2d0357fe5f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6772696d7a792f6c61726176656c2d6d7973716c2d7370617469616c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/grimzy/laravel-mysql-spatial)[![Packagist](https://camo.githubusercontent.com/ca275852df946c456ff6f008000508c88bd44f92984dfc9bf533be89e0cb7f5a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6772696d7a792f6c61726176656c2d6d7973716c2d7370617469616c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/grimzy/laravel-mysql-spatial) [![StyleCI](https://camo.githubusercontent.com/f614637c76386fdb94b4d036bb55d3fdde54cb9e5a4b0c903692764525a3eb70/68747470733a2f2f6769746875622e7374796c6563692e696f2f7265706f732f38333736363134312f736869656c643f6272616e63683d6d6173746572)](https://github.styleci.io/repos/83766141)[![license](https://camo.githubusercontent.com/7123c32787e013be5a8a13598ad01f562754637ed6141e89b02e85bf16d3e63e/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6d6173686170652f6170697374617475732e7376673f7374796c653d666c61742d737175617265)](LICENSE)

Laravel package to easily work with [MySQL Spatial Data Types](https://dev.mysql.com/doc/refman/8.0/en/spatial-type-overview.html) and [MySQL Spatial Functions](https://dev.mysql.com/doc/refman/8.0/en/spatial-function-reference.html).

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**

- `1.x.x`: MySQL 5.6 (also supports MySQL 5.5 but not all spatial analysis functions)
- `2.x.x`: MySQL 5.7 and 8.0

This package also works with MariaDB. Please refer to the [MySQL/MariaDB Spatial Support Matrix](https://mariadb.com/kb/en/library/mysqlmariadb-spatial-support-matrix/) for compatibility.

Installation
------------

[](#installation)

Add the package using composer:

```
composer require grimzy/laravel-mysql-spatial
```

For MySQL 5.6 and 5.5:

```
composer require grimzy/laravel-mysql-spatial:^1.0
```

For Laravel versions before 5.5 or if not using auto-discovery, register the service provider in `config/app.php`:

```
'providers' => [
  /*
   * Package Service Providers...
   */
  Grimzy\LaravelMysqlSpatial\SpatialServiceProvider::class,
],
```

Quickstart
----------

[](#quickstart)

### Create a migration

[](#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. For Laravel versions prior to 5.5, you can use the Blueprint provided by this package (Grimzy\\LaravelMysqlSpatial\\Schema\\Blueprint):

```
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;

// For Laravel < 5.5
// use Grimzy\LaravelMysqlSpatial\Schema\Blueprint;

class CreatePlacesTable extends Migration {

    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        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();
        });
    }

    /**
     * Reverse the migrations.
     *
     * @return void
     */
    public function down()
    {
        Schema::drop('places');
    }
}
```

Run the migration:

```
php artisan migrate
```

### Create a model

[](#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 Grimzy\LaravelMysqlSpatial\Eloquent\SpatialTrait;

/**
 * @property \Grimzy\LaravelMysqlSpatial\Types\Point   $location
 * @property \Grimzy\LaravelMysqlSpatial\Types\Polygon $area
 */
class Place extends Model
{
    use SpatialTrait;

    protected $fillable = [
        'name'
    ];

    protected $spatialFields = [
        'location',
        'area'
    ];
}
```

### Saving a model

[](#saving-a-model)

```
use Grimzy\LaravelMysqlSpatial\Types\Point;
use Grimzy\LaravelMysqlSpatial\Types\Polygon;

$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();

$place1->area = new Polygon();
```

### Retrieving a model

[](#retrieving-a-model)

```
$place2 = Place::first();
$lat = $place2->location->getLat();	// 40.7484404
$lng = $place2->location->getLng();	// -73.9878441
```

Geometry classes
----------------

[](#geometry-classes)

### Available Geometry classes

[](#available-geometry-classes)

Grimzy\\LaravelMysqlSpatial\\TypesOpenGIS Class`Point($lat, $lng)`[Point](https://dev.mysql.com/doc/refman/8.0/en/gis-class-point.html)`MultiPoint(Point[])`[MultiPoint](https://dev.mysql.com/doc/refman/8.0/en/gis-class-multipoint.html)`LineString(Point[])`[LineString](https://dev.mysql.com/doc/refman/8.0/en/gis-class-linestring.html)`MultiLineString(LineString[])`[MultiLineString](https://dev.mysql.com/doc/refman/8.0/en/gis-class-multilinestring.html)`Polygon(LineString[])` *([exterior and interior boundaries](https://dev.mysql.com/doc/refman/8.0/en/gis-class-polygon.html))*[Polygon](https://dev.mysql.com/doc/refman/8.0/en/gis-class-polygon.html)`MultiPolygon(Polygon[])`[MultiPolygon](https://dev.mysql.com/doc/refman/8.0/en/gis-class-multipolygon.html)`GeometryCollection(Geometry[])`[GeometryCollection](https://dev.mysql.com/doc/refman/8.0/en/gis-class-geometrycollection.html)Check out the [Class diagram](https://user-images.githubusercontent.com/1837678/30788608-a5afd894-a16c-11e7-9a51-0a08b331d4c4.png).

### Using Geometry classes

[](#using-geometry-classes)

In order for your Eloquent Model to handle the Geometry classes, it must use the `Grimzy\LaravelMysqlSpatial\Eloquent\SpatialTrait` trait and define a `protected` property `$spatialFields` as an array of MySQL Spatial Data Type column names (example in [Quickstart](#user-content-create-a-model)).

#### IteratorAggregate and ArrayAccess

[](#iteratoraggregate-and-arrayaccess)

The "composite" Geometries (`LineString`, `Polygon`, `MultiPoint`, `MultiLineString`, and `GeometryCollection`) implement [`IteratorAggregate`](http://php.net/manual/en/class.iteratoraggregate.php) and [`ArrayAccess`](http://php.net/manual/en/class.arrayaccess.php); 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

[](#helpers)

##### From/To Well Known Text ([WKT](https://dev.mysql.com/doc/refman/5.7/en/gis-data-formats.html#gis-wkt-format))

[](#fromto-well-known-text-wkt)

```
// fromWKT($wkt)
$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

[](#fromto-string)

```
// fromString($wkt)
$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](http://geojson.org/))

[](#fromto-json-geojson)

The Geometry classes implement [`JsonSerializable`](http://php.net/manual/en/class.jsonserializable.php) 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
----------------------------------

[](#scopes-spatial-analysis-functions)

Spatial analysis functions are implemented using [Eloquent Local Scopes](https://laravel.com/docs/5.4/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](https://dev.mysql.com/doc/refman/5.7/en/spatial-function-reference.html)).*

Migrations
----------

[](#migrations)

For Laravel versions prior to 5.5, you can use the Blueprint provided with this package: `Grimzy\LaravelMysqlSpatial\Schema\Blueprint`.

```
use Illuminate\Database\Migrations\Migration;
use Grimzy\LaravelMysqlSpatial\Schema\Blueprint;

class CreatePlacesTable extends Migration {
    // ...
}
```

### Columns

[](#columns)

Available [MySQL Spatial Types](https://dev.mysql.com/doc/refman/5.7/en/spatial-datatypes.html) migration blueprints:

- `$table->geometry('column_name')`
- `$table->point('column_name')`
- `$table->lineString('column_name')`
- `$table->polygon('column_name')`
- `$table->multiPoint('column_name')`
- `$table->multiLineString('column_name')`
- `$table->multiPolygon('column_name')`
- `$table->geometryCollection('column_name')`

### Spatial indexes

[](#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](https://dev.mysql.com/doc/refman/5.7/en/creating-spatial-indexes.html):

> For [`MyISAM`](https://dev.mysql.com/doc/refman/5.7/en/myisam-storage-engine.html) 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**](https://laravel.com/docs/5.5/migrations#indexes) regarding Index Lengths in the Laravel 5.6 documentation.

For example, as a follow up to the [Quickstart](#user-content-create-a-migration); 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
-----

[](#tests)

```
composer test
# or
composer test:unit
composer test:integration
```

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 a MySQL 5.7
```

Contributing
------------

[](#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
-------

[](#credits)

Originally inspired from [njbarrett's Laravel postgis package](https://github.com/njbarrett/laravel-postgis).

###  Health Score

29

—

LowBetter than 60% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity7

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity67

Established project with proven stability

 Bus Factor1

Top contributor holds 78.4% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~56 days

Recently: every ~47 days

Total

15

Last Release

2479d ago

Major Versions

1.1.0 → 2.0.02017-08-26

1.1.1 → 2.0.12017-09-03

1.1.2 → 2.0.32018-03-04

1.1.3 → 2.1.22019-02-05

1.1.4 → 2.1.32019-03-04

PHP version history (2 changes)1.0.0PHP &gt;=5.5

1.1.0PHP &gt;=5.5.9

### Community

Maintainers

![](https://www.gravatar.com/avatar/756849ebeca42e3f736c3c31d36fdf499274eda44a9900c3bbc2afd314f2c156?d=identicon)[Kreateyou](/maintainers/Kreateyou)

---

Top Contributors

[![grimzy](https://avatars.githubusercontent.com/u/1837678?v=4)](https://github.com/grimzy "grimzy (98 commits)")[![Dylan-DutchAndBold](https://avatars.githubusercontent.com/u/36036362?v=4)](https://github.com/Dylan-DutchAndBold "Dylan-DutchAndBold (8 commits)")[![davidpiesse](https://avatars.githubusercontent.com/u/800650?v=4)](https://github.com/davidpiesse "davidpiesse (6 commits)")[![Kreateyou](https://avatars.githubusercontent.com/u/37910250?v=4)](https://github.com/Kreateyou "Kreateyou (4 commits)")[![antonkomarev](https://avatars.githubusercontent.com/u/1849174?v=4)](https://github.com/antonkomarev "antonkomarev (4 commits)")[![astrogin](https://avatars.githubusercontent.com/u/13066161?v=4)](https://github.com/astrogin "astrogin (3 commits)")[![jl9404](https://avatars.githubusercontent.com/u/1576809?v=4)](https://github.com/jl9404 "jl9404 (1 commits)")[![bricehartmann](https://avatars.githubusercontent.com/u/9779486?v=4)](https://github.com/bricehartmann "bricehartmann (1 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/kreateyou-grimzy-octobercms-mysql-spatial/health.svg)

```
[![Health](https://phpackages.com/badges/kreateyou-grimzy-octobercms-mysql-spatial/health.svg)](https://phpackages.com/packages/kreateyou-grimzy-octobercms-mysql-spatial)
```

###  Alternatives

[fumeapp/modeltyper

Generate TypeScript interfaces from Laravel Models

196277.9k](/packages/fumeapp-modeltyper)[ajthinking/laravel-postgis

Postgis extensions for laravel. Aims to make it easy to work with geometries from laravel models

1572.4k](/packages/ajthinking-laravel-postgis)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

255.2k](/packages/aedart-athenaeum)[limenet/laravel-mysql-spatial

MySQL spatial data types extension for Laravel.

1214.2k](/packages/limenet-laravel-mysql-spatial)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)