Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 9bbadd7

Browse files
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)

AltStyle によって変換されたページ (->オリジナル) /