Added documentation. Updated readme. Updated composer.json.

grimzy · Aug 26, 2017 · 65f6ab1 · 65f6ab1
1 parent fe4f638
commit 65f6ab1
Show file tree

Hide file tree

Showing 4 changed files with 72 additions and 21 deletions.
diff --git a/README.md b/README.md
@@ -11,12 +11,23 @@ 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:
 
 ```shell
-composer require astrogin/laravel-mysql-spatial
+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`:
@@ -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
 

diff --git a/composer.json b/composer.json
@@ -16,7 +16,7 @@
         "jmikola/geojson": "^1.0"
     },
     "require-dev": {
-        "phpunit/phpunit": "~4.5||5.6.5",
+        "phpunit/phpunit": "~5.7",
         "mockery/mockery": "^0.9.9",
         "laravel/laravel": "^5.2",
         "codeclimate/php-test-reporter": "dev-master",
@@ -35,7 +35,7 @@
     },
     "extra": {
         "branch-alias": {
-            "dev-master": "1.0.x-dev"
+            "dev-master": "2.0.x-dev"
         }
     }
 }
diff --git a/src/Eloquent/SpatialTrait.php b/src/Eloquent/SpatialTrait.php
@@ -7,6 +7,25 @@
 use Grimzy\LaravelMysqlSpatial\Types\GeometryInterface;
 use Illuminate\Database\Eloquent\Builder as EloquentBuilder;
 
+/**
+ * Trait SpatialTrait
+ *
+ * @package Grimzy\LaravelMysqlSpatial\Eloquent
+ *
+ * @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
 {
     /*
@@ -170,4 +189,4 @@ public function scopeDoesTouch($query, $geometryColumn, $geometry)
     {
         return $this->scopeComparison($query, $geometryColumn, $geometry, 'touches');
     }
-}
+}
diff --git a/tests/Unit/Eloquent/SpatialTraitTest.php b/tests/Unit/Eloquent/SpatialTraitTest.php
@@ -306,7 +306,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();
@@ -316,7 +316,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();
@@ -326,7 +326,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();
@@ -336,7 +336,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();
@@ -346,7 +346,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();
@@ -356,7 +356,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();
@@ -366,7 +366,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();
@@ -376,7 +376,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();
@@ -386,7 +386,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();