Skip to content

Commit 81d19e6

Browse files
MatanYadaevMatanYadaev
committed
ready
1 parent c47462d commit 81d19e6

File tree

1 file changed

+185
-28
lines changed

1 file changed

+185
-28
lines changed

‎API.md‎

Lines changed: 185 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -12,18 +12,36 @@
1212

1313
## Available spatial functions
1414

15-
* `toWkt` - Mostly used internally
16-
* `toArray`
17-
* `toJson`
18-
* `fromWkb` - Mostly used internally
19-
* `fromJson`
20-
* `toFeatureCollectionJson`
21-
* `getCoordinates`
15+
Every geometry class has these functions:
2216

23-
Geometry collection functions:
17+
* `toArray()` - Serializes the geometry object into a GeoJSON array.
18+
* `toJson()` - Serializes the geometry object into an GeoJSON string.
19+
* `fromJson(string $json)` - Deserializes a geometry object from a GeoJSON string. (static method)
20+
* `toFeatureCollectionJson()` - Serializes the geometry object into an GeoJSON string wrapped by a FeatureCollection.
21+
* `getCoordinates()` - Returns the coordinates of the geometry object.
2422

25-
* `toCollectionWkt` - Mostly used internally
26-
* `getGeometries` - (explanation...) Can be used with `ArrayAccess` as well
23+
In addition, `GeometryCollection` also has these functions:
24+
25+
* `getGeometries()` - Returns a geometry array. Can be used with `ArrayAccess` as well.
26+
```php
27+
$geometryCollection = new GeometryCollection([
28+
new Polygon([
29+
new LineString([
30+
new Point(180, 0),
31+
new Point(179, 1),
32+
new Point(178, 2),
33+
new Point(177, 3),
34+
new Point(180, 0),
35+
]),
36+
]),
37+
new Point(180, 0),
38+
]),
39+
]);
40+
41+
echo $geometryCollection->getGeometries()[1]->latitude; // 180
42+
// can also access as an array:
43+
echo $geometryCollection[1]->latitude; // 180
44+
```
2745

2846
## Available spatial scopes
2947

@@ -33,10 +51,17 @@ Geometry collection functions:
3351
* [withDistanceSphere](#withDistanceSphere)
3452
* [whereDistanceSphere](#whereDistanceSphere)
3553
* [orderByDistanceSphere](#orderByDistanceSphere)
54+
* [whereWithin](#whereWithin)
55+
* [whereContains](#whereContains)
56+
* [whereTouches](#whereTouches)
57+
* [whereIntersects](#whereIntersects)
58+
* [whereCrosses](#whereCrosses)
59+
* [whereDisjoint](#whereDisjoint)
60+
* [whereEquals](#whereEquals)
3661

3762
### withDistance
3863

39-
Retrieves the distance between 2 geometry objects. Uses [ST_Distance](https://dev.mysql.com/doc/refman/8.0/en/spatial-relation-functions-object-shapes.html#function_st-distance)
64+
Retrieves the distance between 2 geometry objects. Uses [ST_Distance](https://dev.mysql.com/doc/refman/8.0/en/spatial-relation-functions-object-shapes.html#function_st-distance).
4065

4166
| parameter name | type | default |
4267
| ------------------ | -------------------- | ------- |
@@ -66,7 +91,7 @@ echo $placeWithDistance->distance_in_meters; // 1.4142135623731
6691

6792
### whereDistance
6893

69-
Filters records by distance. Uses [ST_Distance](https://dev.mysql.com/doc/refman/8.0/en/spatial-relation-functions-object-shapes.html#function_st-distance)
94+
Filters records by distance. Uses [ST_Distance](https://dev.mysql.com/doc/refman/8.0/en/spatial-relation-functions-object-shapes.html#function_st-distance).
7095

7196
| parameter name | type
7297
| ------------------ | --------------------
@@ -91,7 +116,7 @@ echo $placesCountWithinDistance; // 1
91116

92117
### orderByDistance
93118

94-
Orders records by distance. Uses [ST_Distance](https://dev.mysql.com/doc/refman/8.0/en/spatial-relation-functions-object-shapes.html#function_st-distance)
119+
Orders records by distance. Uses [ST_Distance](https://dev.mysql.com/doc/refman/8.0/en/spatial-relation-functions-object-shapes.html#function_st-distance).
95120

96121
| parameter name | type | default |
97122
| ------------------ | -------------------- | ------- |
@@ -122,7 +147,7 @@ echo $places[1]->name; // first
122147

123148
### withDistanceSphere
124149

125-
Retrieves the spherical distance between 2 geometry objects. Uses [ST_Distance_Sphere](https://dev.mysql.com/doc/refman/8.0/en/spatial-convenience-functions.html#function_st-distance-sphere)
150+
Retrieves the spherical distance between 2 geometry objects. Uses [ST_Distance_Sphere](https://dev.mysql.com/doc/refman/8.0/en/spatial-convenience-functions.html#function_st-distance-sphere).
126151

127152
| parameter name | type | default |
128153
| ------------------ | -------------------- | ------- |
@@ -150,9 +175,9 @@ echo $placeWithDistance->distance_in_meters; // 157249.0357231545
150175
```
151176
</details>
152177

153-
### whereDistance
178+
### whereDistanceSphere
154179

155-
Filters records by spherical distance. Uses [ST_Distance_Sphere](https://dev.mysql.com/doc/refman/8.0/en/spatial-convenience-functions.html#function_st-distance-sphere)
180+
Filters records by spherical distance. Uses [ST_Distance_Sphere](https://dev.mysql.com/doc/refman/8.0/en/spatial-convenience-functions.html#function_st-distance-sphere).
156181

157182
| parameter name | type
158183
| ------------------ | --------------------
@@ -168,16 +193,16 @@ Place::create(['location' => new Point(0, 0)]);
168193
Place::create(['location' => new Point(100, 100)]);
169194

170195
$placesCountWithinDistance = Place::query()
171-
->whereDistance('location', new Point(1, 1), '<', 160000)
196+
->whereDistanceSphere('location', new Point(1, 1), '<', 160000)
172197
->count();
173198

174199
echo $placesCountWithinDistance; // 1
175200
```
176201
</details>
177202

178-
### orderByDistance
203+
### orderByDistanceSphere
179204

180-
Orders records by spherical distance. Uses [ST_Distance_Sphere](https://dev.mysql.com/doc/refman/8.0/en/spatial-convenience-functions.html#function_st-distance-sphere)
205+
Orders records by spherical distance. Uses [ST_Distance_Sphere](https://dev.mysql.com/doc/refman/8.0/en/spatial-convenience-functions.html#function_st-distance-sphere).
181206

182207
| parameter name | type | default |
183208
| ------------------ | -------------------- | ------- |
@@ -198,19 +223,151 @@ Place::create([
198223
]);
199224

200225
$places = Place::query()
201-
->orderByDistance('location', new Point(1, 1), 'desc')
226+
->orderByDistanceSphere('location', new Point(1, 1), 'desc')
202227
->get();
203228

204229
echo $places[0]->name; // second
205230
echo $places[1]->name; // first
206231
```
207232
</details>
208233

209-
* `whereWithin(string $column, Geometry | string $geometryOrColumn)`
210-
* `whereContains(string $column, Geometry | string $geometryOrColumn)`
211-
* `whereTouches(string $column, Geometry | string $geometryOrColumn)`
212-
* `whereIntersects(string $column, Geometry | string $geometryOrColumn)`
213-
* `whereCrosses(string $column, Geometry | string $geometryOrColumn)`
214-
* `whereDisjoint(string $column, Geometry | string $geometryOrColumn)`
215-
* `whereOverlaps(string $column, Geometry | string $geometryOrColumn)`
216-
* `whereEquals(string $column, Geometry | string $geometryOrColumn)`
234+
### whereWithin
235+
236+
Filters records by the [ST_Within](https://dev.mysql.com/doc/refman/8.0/en/spatial-relation-functions-object-shapes.html#function_st-within) function.
237+
238+
| parameter name | type
239+
| ------------------ | --------------------
240+
| `$column` | `string`
241+
| `$geometryOrColumn` | `Geometry \| string`
242+
243+
<details><summary>Example</summary>
244+
245+
```php
246+
Place::create(['location' => new Point(0, 0)]);
247+
248+
Place::query()
249+
->whereWithin('location', Polygon::fromJson('{"type":"Polygon","coordinates":[[[-1,-1],[1,-1],[1,1],[-1,1],[-1,-1]]]}'))
250+
->exists(); // true
251+
```
252+
</details>
253+
254+
### whereContains
255+
256+
Filters records by the [ST_Contains](https://dev.mysql.com/doc/refman/8.0/en/spatial-relation-functions-object-shapes.html#function_st-contains) function.
257+
258+
| parameter name | type
259+
| ------------------ | --------------------
260+
| `$column` | `string`
261+
| `$geometryOrColumn` | `Geometry \| string`
262+
263+
<details><summary>Example</summary>
264+
265+
```php
266+
Place::create(['area' => Polygon::fromJson('{"type":"Polygon","coordinates":[[[-1,-1],[1,-1],[1,1],[-1,1],[-1,-1]]]}'),]);
267+
268+
Place::query()
269+
->whereContains('area', new Point(0, 0))
270+
->exists(); // true
271+
```
272+
</details>
273+
274+
### whereTouches
275+
276+
Filters records by the [ST_Touches](https://dev.mysql.com/doc/refman/8.0/en/spatial-relation-functions-object-shapes.html#function_st-touches) function.
277+
278+
| parameter name | type
279+
| ------------------ | --------------------
280+
| `$column` | `string`
281+
| `$geometryOrColumn` | `Geometry \| string`
282+
283+
<details><summary>Example</summary>
284+
285+
```php
286+
Place::create(['location' => new Point(0, 0)]);
287+
288+
Place::query()
289+
->whereTouches('location', Polygon::fromJson('{"type":"Polygon","coordinates":[[[-1,-1],[0,-1],[0,0],[-1,0],[-1,-1]]]}'))
290+
->exists(); // true
291+
```
292+
</details>
293+
294+
### whereIntersects
295+
296+
Filters records by the [ST_Intersects](https://dev.mysql.com/doc/refman/8.0/en/spatial-relation-functions-object-shapes.html#function_st-intersects) function.
297+
298+
| parameter name | type
299+
| ------------------ | --------------------
300+
| `$column` | `string`
301+
| `$geometryOrColumn` | `Geometry \| string`
302+
303+
<details><summary>Example</summary>
304+
305+
```php
306+
Place::create(['location' => new Point(0, 0)]);
307+
308+
Place::query()
309+
->whereIntersects('location', Polygon::fromJson('{"type":"Polygon","coordinates":[[[-1,-1],[1,-1],[1,1],[-1,1],[-1,-1]]]}'))
310+
->exists(); // true
311+
```
312+
</details>
313+
314+
### whereCrosses
315+
316+
Filters records by the [ST_Crosses](https://dev.mysql.com/doc/refman/8.0/en/spatial-relation-functions-object-shapes.html#function_st-crosses) function.
317+
318+
| parameter name | type
319+
| ------------------ | --------------------
320+
| `$column` | `string`
321+
| `$geometryOrColumn` | `Geometry \| string`
322+
323+
<details><summary>Example</summary>
324+
325+
```php
326+
Place::create(['line_string' => LineString::fromJson('{"type":"LineString","coordinates":[[0,0],[2,0]]}')]);
327+
328+
Place::query()
329+
->whereCrosses('line_string', Polygon::fromJson('{"type":"Polygon","coordinates":[[[-1,-1],[1,-1],[1,1],[-1,1],[-1,-1]]]}'))
330+
->exists(); // true
331+
```
332+
</details>
333+
334+
### whereDisjoint
335+
336+
Filters records by the [ST_Disjoint](https://dev.mysql.com/doc/refman/8.0/en/spatial-relation-functions-object-shapes.html#function_st-disjoint) function.
337+
338+
| parameter name | type
339+
| ------------------ | --------------------
340+
| `$column` | `string`
341+
| `$geometryOrColumn` | `Geometry \| string`
342+
343+
<details><summary>Example</summary>
344+
345+
```php
346+
Place::create(['location' => new Point(0, 0)]);
347+
348+
Place::query()
349+
->whereDisjoint('location', Polygon::fromJson('{"type":"Polygon","coordinates":[[[-1,-1],[-0.5,-1],[-0.5,-0.5],[-1,-0.5],[-1,-1]]]}'))
350+
->exists(); // true
351+
```
352+
</details>
353+
354+
### whereEquals
355+
356+
Filters records by the [ST_Equal](https://dev.mysql.com/doc/refman/8.0/en/spatial-relation-functions-object-shapes.html#function_st-equals) function.
357+
358+
| parameter name | type
359+
| ------------------ | --------------------
360+
| `$column` | `string`
361+
| `$geometryOrColumn` | `Geometry \| string`
362+
363+
<details><summary>Example</summary>
364+
365+
```php
366+
Place::create(['location' => new Point(0, 0)]);
367+
368+
Place::query()
369+
->whereEquals('location', new Point(0, 0))
370+
->exists(); // true
371+
```
372+
</details>
373+

0 commit comments

Comments
 (0)