Added documentation. Updated readme. Updated composer.json.

Author: grimzy

README.md

@@ -11,6 +11,11 @@ Laravel package to easily work with [MySQL Spatial Data Types](https://dev.mysql
 
 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
+
 ## Installation
 
 Add the package using composer:
@@ -19,6 +24,12 @@ Add the package using composer:
 composer require grimzy/laravel-mysql-spatial
 ```
 
+For MySQL 5.6 and 5.5:
+
+```shell
+composer require grimzy/laravel-mysql-spatial:^1.0
+```
+
 Register the service provider in `config/app.php`:
 
 ```php
@@ -211,14 +222,35 @@ class UpdatePlacesTable extends Migration
 
 Available geometry classes:
 
-- Point
-- LineString
-- Polygon
-- MultiPoint
-- MultiLineString
-- MultiPolygon
-- GeometryCollection
-
+- `Point($lat, $lng)`
+- `MultiPoint(Point[])`
+- `LineString(Point[])`
+- `MultiLineString(LineString[])`
+- `Polygon(LineString[])`
+- `MultiPolygon(Polygon[])`
+- `GeometryCollection(Geometry[])` *(a collection of spatial models)*
+
+## 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)`
+- `touches($geometryColumn, $geometry)`
+
+*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)).*
 
 ## Credits
 

composer.json

@@ -35,7 +35,7 @@
     },
     "extra": {
         "branch-alias": {
-            "dev-master": "1.0.x-dev"
+            "dev-mysql-5.6": "1.0.x-dev"
         }
     }
 }

src/Eloquent/SpatialTrait.php

@@ -7,6 +7,23 @@
 use Grimzy\LaravelMysqlSpatial\Types\GeometryInterface;
 use Illuminate\Database\Eloquent\Builder as EloquentBuilder;
 
+/**
+ * Trait SpatialTrait
+ *
+ * @method static distance($geometryColumn, $geometry, $distance)
+ * @method static distanceExcludingSelf($geometryColumn, $geometry, $distance)
+ * @method static distanceSphere($geometryColumn, $geometry, $distance)
+ * @method static distanceSphereExcludingSelf($geometryColumn, $geometry, $distance)
+ * @method static comparison($geometryColumn, $geometry, $relationship)
+ * @method static within($geometryColumn, $polygon)
+ * @method static crosses($geometryColumn, $geometry)
+ * @method static contains($geometryColumn, $geometry)
+ * @method static disjoint($geometryColumn, $geometry)
+ * @method static equals($geometryColumn, $geometry)
+ * @method static intersects($geometryColumn, $geometry)
+ * @method static overlaps($geometryColumn, $geometry)
+ * @method static touches($geometryColumn, $geometry)
+ */
 trait SpatialTrait
 {
     /*

tests/Unit/Eloquent/SpatialTraitTest.php

@@ -194,7 +194,7 @@ public function testInsertUpdateGeometryCollectionHasCorrectSql()
     public function testScopeDistance()
     {
         $point = new Point(1, 2);
-        $query = TestModel::Distance('point', $point, 10);
+        $query = TestModel::distance('point', $point, 10);
 
         $this->assertInstanceOf(\Grimzy\LaravelMysqlSpatial\Eloquent\Builder::class, $query);
         $q = $query->getQuery();
@@ -205,7 +205,7 @@ public function testScopeDistance()
     public function testScopeDistanceExcludingSelf()
     {
         $point = new Point(1, 2);
-        $query = TestModel::Distance('point', $point, 10, true);
+        $query = TestModel::distance('point', $point, 10, true);
 
         $this->assertInstanceOf(\Grimzy\LaravelMysqlSpatial\Eloquent\Builder::class, $query);
         $q = $query->getQuery();
@@ -217,7 +217,7 @@ public function testScopeDistanceExcludingSelf()
     public function testScopeDistanceValue()
     {
         $point = new Point(1, 2);
-        $query = TestModel::DistanceValue('point', $point);
+        $query = TestModel::distanceValue('point', $point);
 
         $this->assertInstanceOf(\Grimzy\LaravelMysqlSpatial\Eloquent\Builder::class, $query);
         $q = $query->getQuery();
@@ -257,7 +257,7 @@ private function buildTestPolygon()
 
     public function testScopeComparison()
     {
-        $query = TestModel::Comparison('point', $this->buildTestPolygon(), 'within');
+        $query = TestModel::comparison('point', $this->buildTestPolygon(), 'within');
 
         $this->assertInstanceOf(\Grimzy\LaravelMysqlSpatial\Eloquent\Builder::class, $query);
         $q = $query->getQuery();
@@ -267,7 +267,7 @@ public function testScopeComparison()
 
     public function testScopeWithin()
     {
-        $query = TestModel::Within('point', $this->buildTestPolygon());
+        $query = TestModel::within('point', $this->buildTestPolygon());
 
         $this->assertInstanceOf(\Grimzy\LaravelMysqlSpatial\Eloquent\Builder::class, $query);
         $q = $query->getQuery();
@@ -277,7 +277,7 @@ public function testScopeWithin()
 
     public function testScopeCrosses()
     {
-        $query = TestModel::Crosses('point', $this->buildTestPolygon());
+        $query = TestModel::crosses('point', $this->buildTestPolygon());
 
         $this->assertInstanceOf(\Grimzy\LaravelMysqlSpatial\Eloquent\Builder::class, $query);
         $q = $query->getQuery();
@@ -287,7 +287,7 @@ public function testScopeCrosses()
 
     public function testScopeContains()
     {
-        $query = TestModel::Contains('point', $this->buildTestPolygon());
+        $query = TestModel::contains('point', $this->buildTestPolygon());
 
         $this->assertInstanceOf(\Grimzy\LaravelMysqlSpatial\Eloquent\Builder::class, $query);
         $q = $query->getQuery();
@@ -297,7 +297,7 @@ public function testScopeContains()
 
     public function testScopeDisjoint()
     {
-        $query = TestModel::Disjoint('point', $this->buildTestPolygon());
+        $query = TestModel::disjoint('point', $this->buildTestPolygon());
 
         $this->assertInstanceOf(\Grimzy\LaravelMysqlSpatial\Eloquent\Builder::class, $query);
         $q = $query->getQuery();
@@ -307,7 +307,7 @@ public function testScopeDisjoint()
 
     public function testScopeEquals()
     {
-        $query = TestModel::Equals('point', $this->buildTestPolygon());
+        $query = TestModel::equals('point', $this->buildTestPolygon());
 
         $this->assertInstanceOf(\Grimzy\LaravelMysqlSpatial\Eloquent\Builder::class, $query);
         $q = $query->getQuery();
@@ -317,7 +317,7 @@ public function testScopeEquals()
 
     public function testScopeIntersects()
     {
-        $query = TestModel::Intersects('point', $this->buildTestPolygon());
+        $query = TestModel::intersects('point', $this->buildTestPolygon());
 
         $this->assertInstanceOf(\Grimzy\LaravelMysqlSpatial\Eloquent\Builder::class, $query);
         $q = $query->getQuery();
@@ -327,7 +327,7 @@ public function testScopeIntersects()
 
     public function testScopeOverlaps()
     {
-        $query = TestModel::Overlaps('point', $this->buildTestPolygon());
+        $query = TestModel::overlaps('point', $this->buildTestPolygon());
 
         $this->assertInstanceOf(\Grimzy\LaravelMysqlSpatial\Eloquent\Builder::class, $query);
         $q = $query->getQuery();
@@ -337,7 +337,7 @@ public function testScopeOverlaps()
 
     public function testScopeDoesTouch()
     {
-        $query = TestModel::DoesTouch('point', $this->buildTestPolygon());
+        $query = TestModel::doesTouch('point', $this->buildTestPolygon());
 
         $this->assertInstanceOf(\Grimzy\LaravelMysqlSpatial\Eloquent\Builder::class, $query);
         $q = $query->getQuery();