Skip to content

Commit 9bbadd7

Browse files
grimzygrimzy
committed
Updated doc 📖
1 parent eb01c85 commit 9bbadd7

File tree

1 file changed

+76
-30
lines changed

1 file changed

+76
-30
lines changed

‎README.md

Lines changed: 76 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -13,22 +13,29 @@ Please check the documentation for your MySQL version. MySQL's Extension for Spa
1313
**Versions**
1414

1515
- `1.x.x`: MySQL 5.6 (also supports MySQL 5.5 but not all spatial analysis functions)
16-
- `2.x.x`: MySQL 5.7 and 8.0
16+
- `2.x.x`: MySQL 5.7
17+
- **`3.x.x`: MySQL 8.0 with SRID support (Current branch)**
1718

1819
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.
1920

2021
## Installation
2122

2223
Add the package using composer:
2324

25+
```sh
26+
$ composer require grimzy/laravel-mysql-spatial
27+
```
28+
29+
For MySQL 5.7:
30+
2431
```shell
25-
composer require grimzy/laravel-mysql-spatial
32+
$ composer require grimzy/laravel-mysql-spatial:^2.0
2633
```
2734

2835
For MySQL 5.6 and 5.5:
2936

3037
```shell
31-
composer require grimzy/laravel-mysql-spatial:^1.0
38+
$ composer require grimzy/laravel-mysql-spatial:^1.0
3239
```
3340

3441
For Laravel versions before 5.5 or if not using auto-discovery, register the service provider in `config/app.php`:
@@ -80,6 +87,19 @@ class CreatePlacesTable extends Migration {
8087
$table->polygon('area')->nullable();
8188
$table->timestamps();
8289
});
90+
91+
// Or create the spatial fields with an SRID (e.g. 4326 WGS84 spheroid)
92+
93+
// Schema::create('places', function(Blueprint $table)
94+
// {
95+
// $table->increments('id');
96+
// $table->string('name')->unique();
97+
// // Add a Point spatial data field named location with SRID 4326
98+
// $table->point('location', 4326)->nullable();
99+
// // Add a Polygon spatial data field named area with SRID 4326
100+
// $table->polygon('area', 4326)->nullable();
101+
// $table->timestamps();
102+
// });
83103
}
84104

85105
/**
@@ -158,11 +178,37 @@ $place1->area = new Polygon([new LineString([
158178
new Point(40.74894149554006, -73.98615270853043)
159179
])]);
160180
$place1->save();
181+
```
182+
183+
Or if your database fields were created with a specific SRID:
184+
185+
```php
186+
use Grimzy\LaravelMysqlSpatial\Types\Point;
187+
use Grimzy\LaravelMysqlSpatial\Types\Polygon;
188+
use Grimzy\LaravelMysqlSpatial\Types\LineString;
189+
190+
$place1 = new Place();
191+
$place1->name = 'Empire State Building';
161192

162-
$place1->area = new Polygon();
193+
// saving a point with SRID 4326 (WGS84 spheroid)
194+
$place1->location = new Point(40.7484404, -73.9878441, 4326); // (lat, lng, srid)
195+
$place1->save();
163196

197+
// saving a polygon with SRID 4326 (WGS84 spheroid)
198+
$place1->area = new Polygon([new LineString([
199+
new Point(40.74894149554006, -73.98615270853043),
200+
new Point(40.74848633046773, -73.98648262023926),
201+
new Point(40.747925497790725, -73.9851602911949),
202+
new Point(40.74837050671544, -73.98482501506805),
203+
new Point(40.74894149554006, -73.98615270853043)
204+
])], 4326);
205+
$place1->save();
164206
```
165207

208+
> **Note**: When saving collection Geometries (`LineString`, `Polygon`, `MultiPoint`, `MultiLineString`, and `GeometryCollection`), only the top-most geometry should have an SRID set in the constructor.
209+
>
210+
> 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.
211+
166212
### Retrieving a model
167213

168214
```php
@@ -177,13 +223,13 @@ $lng = $place2->location->getLng(); // -73.9878441
177223

178224
| Grimzy\LaravelMysqlSpatial\Types | OpenGIS Class |
179225
| ------------------------------------------------------------ | ------------------------------------------------------------ |
180-
| `Point($lat, $lng)` | [Point](https://dev.mysql.com/doc/refman/8.0/en/gis-class-point.html) |
181-
| `MultiPoint(Point[])` | [MultiPoint](https://dev.mysql.com/doc/refman/8.0/en/gis-class-multipoint.html) |
182-
| `LineString(Point[])` | [LineString](https://dev.mysql.com/doc/refman/8.0/en/gis-class-linestring.html) |
183-
| `MultiLineString(LineString[])` | [MultiLineString](https://dev.mysql.com/doc/refman/8.0/en/gis-class-multilinestring.html) |
184-
| `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) |
185-
| `MultiPolygon(Polygon[])` | [MultiPolygon](https://dev.mysql.com/doc/refman/8.0/en/gis-class-multipolygon.html) |
186-
| `GeometryCollection(Geometry[])` | [GeometryCollection](https://dev.mysql.com/doc/refman/8.0/en/gis-class-geometrycollection.html) |
226+
| `Point($lat, $lng, $srid = 0)` | [Point](https://dev.mysql.com/doc/refman/8.0/en/gis-class-point.html) |
227+
| `MultiPoint(Point[], $srid = 0)` | [MultiPoint](https://dev.mysql.com/doc/refman/8.0/en/gis-class-multipoint.html) |
228+
| `LineString(Point[], $srid = 0)` | [LineString](https://dev.mysql.com/doc/refman/8.0/en/gis-class-linestring.html) |
229+
| `MultiLineString(LineString[], $srid = 0)` | [MultiLineString](https://dev.mysql.com/doc/refman/8.0/en/gis-class-multilinestring.html) |
230+
| `Polygon(LineString[], $srid = 0)` *([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) |
231+
| `MultiPolygon(Polygon[], $srid = 0)` | [MultiPolygon](https://dev.mysql.com/doc/refman/8.0/en/gis-class-multipolygon.html) |
232+
| `GeometryCollection(Geometry[], $srid = 0)` | [GeometryCollection](https://dev.mysql.com/doc/refman/8.0/en/gis-class-geometrycollection.html) |
187233

188234
Check out the [Class diagram](https://user-images.githubusercontent.com/1837678/30788608-a5afd894-a16c-11e7-9a51-0a08b331d4c4.png).
189235

@@ -193,7 +239,7 @@ In order for your Eloquent Model to handle the Geometry classes, it must use the
193239

194240
#### IteratorAggregate and ArrayAccess
195241

196-
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:
242+
The collection 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:
197243

198244
```php
199245
$polygon = $multipolygon[10]; // ArrayAccess
@@ -210,7 +256,7 @@ for($polygon as $i => $linestring) {
210256
##### From/To Well Known Text ([WKT](https://dev.mysql.com/doc/refman/5.7/en/gis-data-formats.html#gis-wkt-format))
211257

212258
```php
213-
// fromWKT($wkt)
259+
// fromWKT($wkt, $srid = 0)
214260
$point = Point::fromWKT('POINT(2 1)');
215261
$point->toWKT(); // POINT(2 1)
216262

@@ -221,9 +267,9 @@ $polygon->toWKT(); // POLYGON((0 0,4 0,4 4,0 4,0 0),(1 1, 2 1, 2 2, 1 2,1 1))
221267
##### From/To String
222268

223269
```php
224-
// fromString($wkt)
270+
// fromString($wkt, $srid = 0)
225271
$point = new Point(1, 2); // lat, lng
226-
(string)$point // lng, lat: 2 1
272+
(string)$point // lng, lat: 2 1
227273

228274
$polygon = Polygon::fromString('(0 0,4 0,4 4,0 4,0 0),(1 1, 2 1, 2 2, 1 2,1 1)');
229275
(string)$polygon; // (0 0,4 0,4 4,0 4,0 0),(1 1, 2 1, 2 2, 1 2,1 1)
@@ -280,8 +326,8 @@ Available scopes:
280326
- `overlaps($geometryColumn, $geometry)`
281327
- `doesTouch($geometryColumn, $geometry)`
282328
- `orderBySpatial($geometryColumn, $geometry, $orderFunction, $direction = 'asc')`
283-
- `orderByDistance($geometryColumn, ​$geometry, ​$direction = 'asc')`
284-
- `orderByDistanceSphere($geometryColumn, ​$geometry, ​$direction = 'asc')`
329+
- `orderByDistance($geometryColumn, $geometry, $direction = 'asc')`
330+
- `orderByDistanceSphere($geometryColumn, $geometry, $direction = 'asc')`
285331

286332
*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)).*
287333

@@ -302,14 +348,14 @@ class CreatePlacesTable extends Migration {
302348

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

305-
- `$table->geometry('column_name')`
306-
- `$table->point('column_name')`
307-
- `$table->lineString('column_name')`
308-
- `$table->polygon('column_name')`
309-
- `$table->multiPoint('column_name')`
310-
- `$table->multiLineString('column_name')`
311-
- `$table->multiPolygon('column_name')`
312-
- `$table->geometryCollection('column_name')`
351+
- `$table->geometry(string $column_name, int $srid = 0)`
352+
- `$table->point(string $column_name, int $srid = 0)`
353+
- `$table->lineString(string $column_name, int $srid = 0)`
354+
- `$table->polygon(string $column_name, int $srid = 0)`
355+
- `$table->multiPoint(string $column_name, int $srid = 0)`
356+
- `$table->multiLineString(string $column_name, int $srid = 0)`
357+
- `$table->multiPolygon(string $column_name, int $srid = 0)`
358+
- `$table->geometryCollection(string $column_name, int $srid = 0)`
313359

314360
### Spatial indexes
315361

@@ -381,18 +427,18 @@ class UpdatePlacesTable extends Migration
381427
## Tests
382428

383429
```shell
384-
composer test
430+
$ composer test
385431
# or
386-
composer test:unit
387-
composer test:integration
432+
$ composer test:unit
433+
$ composer test:integration
388434
```
389435

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

392438
```shell
393-
make start_db # starts MySQL 8.0
439+
$ make start_db # starts MySQL 8.0
394440
# or
395-
make start_db V=5.7 # starts a MySQL 5.7
441+
$ make start_db V=5.7 # starts MySQL 5.7
396442
```
397443

398444
## Contributing

0 commit comments

Comments
 (0)