Skip to content

Commit c17fb5c

Browse files
MatanYadaevMatanYadaev
authored
Merge pull request #20 from MatanYadaev/initial-docs
Docs
2 parents 24d7d81 + 758310c commit c17fb5c

20 files changed

+838
-226
lines changed

‎.github/workflows/php-cs-fixer.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ jobs:
2020
coverage: none
2121

2222
- name: Install dependencies
23-
run: composer install
23+
run: composer install --prefer-dist --no-interaction
2424

2525
- name: Run PHP CS Fixer
2626
run: ./vendor/bin/php-cs-fixer fix --allow-risky=yes --diff --dry-run

‎API.md

Lines changed: 374 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,374 @@
1+
# API
2+
3+
## Available spatial classes
4+
5+
* `Point(float $latitude, float $longitude)` - [MySQL Point](https://dev.mysql.com/doc/refman/8.0/en/gis-class-point.html)
6+
* `MultiPoint(Point[] | Collection<Point>)` - [MySQL MultiPoint](https://dev.mysql.com/doc/refman/8.0/en/gis-class-multipoint.html)
7+
* `LineString(Point[] | Collection<Point>)` - [MySQL LineString](https://dev.mysql.com/doc/refman/8.0/en/gis-class-linestring.html)
8+
* `MultiLineString(LineString[] | Collection<LineString>)` - [MySQL MultiLineString](https://dev.mysql.com/doc/refman/8.0/en/gis-class-multilinestring.html)
9+
* `Polygon(LineString[] | Collection<LineString>)` - [MySQL Polygon](https://dev.mysql.com/doc/refman/8.0/en/gis-class-polygon.html)
10+
* `MultiPolygon(Polygon[] | Collectiogit n<Polygon>)` - [MySQL MultiPolygon](https://dev.mysql.com/doc/refman/8.0/en/gis-class-multipolygon.html)
11+
* `GeometryCollection(Geometry[] | Collection<Geometry>)` - [MySQL GeometryCollection](https://dev.mysql.com/doc/refman/8.0/en/gis-class-geometrycollection.html)
12+
13+
## Available spatial functions
14+
15+
Every geometry class has these functions:
16+
17+
* `toArray()` - Serializes the geometry object into a GeoJSON associative array.
18+
* `toJson()` - Serializes the geometry object into an GeoJSON string.
19+
* `fromJson(string $geoJson)` - Deserializes a geometry object from a GeoJSON string. (static method)
20+
* `toFeatureCollectionJson()` - Serializes the geometry object into an GeoJSON's FeatureCollection string.
21+
* `getCoordinates()` - Returns the coordinates of the geometry object.
22+
23+
In addition, `GeometryCollection` also has these functions:
24+
25+
* `getGeometries()` - Returns a geometry array. Can be used with `ArrayAccess` as well.
26+
27+
```php
28+
$geometryCollection = new GeometryCollection([
29+
new Polygon([
30+
new LineString([
31+
new Point(180, 0),
32+
new Point(179, 1),
33+
new Point(178, 2),
34+
new Point(177, 3),
35+
new Point(180, 0),
36+
]),
37+
]),
38+
new Point(180, 0),
39+
]),
40+
]);
41+
42+
echo $geometryCollection->getGeometries()[1]->latitude; // 180
43+
// can also access as an array:
44+
echo $geometryCollection[1]->latitude; // 180
45+
```
46+
47+
## Available spatial scopes
48+
49+
* [withDistance](#withDistance)
50+
* [whereDistance](#whereDistance)
51+
* [orderByDistance](#orderByDistance)
52+
* [withDistanceSphere](#withDistanceSphere)
53+
* [whereDistanceSphere](#whereDistanceSphere)
54+
* [orderByDistanceSphere](#orderByDistanceSphere)
55+
* [whereWithin](#whereWithin)
56+
* [whereContains](#whereContains)
57+
* [whereTouches](#whereTouches)
58+
* [whereIntersects](#whereIntersects)
59+
* [whereCrosses](#whereCrosses)
60+
* [whereDisjoint](#whereDisjoint)
61+
* [whereEquals](#whereEquals)
62+
63+
### withDistance
64+
65+
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).
66+
67+
| parameter name | type | default |
68+
| ------------------ | -------------------- | ------- |
69+
| `$column` | `string` |
70+
| `$geometryOrColumn` | `Geometry \| string` |
71+
| `$alias` | `string` | `'distance'`
72+
73+
<details><summary>Example</summary>
74+
75+
```php
76+
Place::create(['location' => new Point(0, 0)]);
77+
78+
$placeWithDistance = Place::query()
79+
->withDistance('location', new Point(1, 1))
80+
->first();
81+
82+
echo $placeWithDistance->distance; // 1.4142135623731
83+
84+
// when using alias:
85+
$placeWithDistance = Place::query()
86+
->withDistance('location', new Point(1, 1), 'distance_in_meters')
87+
->first();
88+
89+
echo $placeWithDistance->distance_in_meters; // 1.4142135623731
90+
```
91+
</details>
92+
93+
### whereDistance
94+
95+
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).
96+
97+
| parameter name | type
98+
| ------------------ | --------------------
99+
| `$column` | `string`
100+
| `$geometryOrColumn` | `Geometry \| string`
101+
| `$operator` | `string`
102+
| `$value` | `int \| float`
103+
104+
<details><summary>Example</summary>
105+
106+
```php
107+
Place::create(['location' => new Point(0, 0)]);
108+
Place::create(['location' => new Point(100, 100)]);
109+
110+
$placesCountWithinDistance = Place::query()
111+
->whereDistance('location', new Point(1, 1), '<', 1.5)
112+
->count();
113+
114+
echo $placesCountWithinDistance; // 1
115+
```
116+
</details>
117+
118+
### orderByDistance
119+
120+
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).
121+
122+
| parameter name | type | default |
123+
| ------------------ | -------------------- | ------- |
124+
| `$column` | `string` |
125+
| `$geometryOrColumn` | `Geometry \| string` |
126+
| `$direction` | `string` | `'asc'`
127+
128+
<details><summary>Example</summary>
129+
130+
```php
131+
Place::create([
132+
'name' => 'first',
133+
'location' => new Point(0, 0),
134+
]);
135+
Place::create([
136+
'name' => 'second',
137+
'location' => new Point(100, 100),
138+
]);
139+
140+
$places = Place::query()
141+
->orderByDistance('location', new Point(1, 1), 'desc')
142+
->get();
143+
144+
echo $places[0]->name; // second
145+
echo $places[1]->name; // first
146+
```
147+
</details>
148+
149+
### withDistanceSphere
150+
151+
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).
152+
153+
| parameter name | type | default |
154+
| ------------------ | -------------------- | ------- |
155+
| `$column` | `string` |
156+
| `$geometryOrColumn` | `Geometry \| string` |
157+
| `$alias` | `string` | `'distance'`
158+
159+
<details><summary>Example</summary>
160+
161+
```php
162+
Place::create(['location' => new Point(0, 0)]);
163+
164+
$placeWithDistance = Place::query()
165+
->withDistanceSphere('location', new Point(1, 1))
166+
->first();
167+
168+
echo $placeWithDistance->distance; // 157249.0357231545
169+
170+
// when using alias:
171+
$placeWithDistance = Place::query()
172+
->withDistanceSphere('location', new Point(1, 1), 'distance_in_meters')
173+
->first();
174+
175+
echo $placeWithDistance->distance_in_meters; // 157249.0357231545
176+
```
177+
</details>
178+
179+
### whereDistanceSphere
180+
181+
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).
182+
183+
| parameter name | type
184+
| ------------------ | --------------------
185+
| `$column` | `string`
186+
| `$geometryOrColumn` | `Geometry \| string`
187+
| `$operator` | `string`
188+
| `$value` | `int \| float`
189+
190+
<details><summary>Example</summary>
191+
192+
```php
193+
Place::create(['location' => new Point(0, 0)]);
194+
Place::create(['location' => new Point(100, 100)]);
195+
196+
$placesCountWithinDistance = Place::query()
197+
->whereDistanceSphere('location', new Point(1, 1), '<', 160000)
198+
->count();
199+
200+
echo $placesCountWithinDistance; // 1
201+
```
202+
</details>
203+
204+
### orderByDistanceSphere
205+
206+
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).
207+
208+
| parameter name | type | default |
209+
| ------------------ | -------------------- | ------- |
210+
| `$column` | `string` |
211+
| `$geometryOrColumn` | `Geometry \| string` |
212+
| `$direction` | `string` | `'asc'`
213+
214+
<details><summary>Example</summary>
215+
216+
```php
217+
Place::create([
218+
'name' => 'first',
219+
'location' => new Point(0, 0),
220+
]);
221+
Place::create([
222+
'name' => 'second',
223+
'location' => new Point(100, 100),
224+
]);
225+
226+
$places = Place::query()
227+
->orderByDistanceSphere('location', new Point(1, 1), 'desc')
228+
->get();
229+
230+
echo $places[0]->name; // second
231+
echo $places[1]->name; // first
232+
```
233+
</details>
234+
235+
### whereWithin
236+
237+
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.
238+
239+
| parameter name | type
240+
| ------------------ | --------------------
241+
| `$column` | `string`
242+
| `$geometryOrColumn` | `Geometry \| string`
243+
244+
<details><summary>Example</summary>
245+
246+
```php
247+
Place::create(['location' => new Point(0, 0)]);
248+
249+
Place::query()
250+
->whereWithin('location', Polygon::fromJson('{"type":"Polygon","coordinates":[[[-1,-1],[1,-1],[1,1],[-1,1],[-1,-1]]]}'))
251+
->exists(); // true
252+
```
253+
</details>
254+
255+
### whereContains
256+
257+
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.
258+
259+
| parameter name | type
260+
| ------------------ | --------------------
261+
| `$column` | `string`
262+
| `$geometryOrColumn` | `Geometry \| string`
263+
264+
<details><summary>Example</summary>
265+
266+
```php
267+
Place::create(['area' => Polygon::fromJson('{"type":"Polygon","coordinates":[[[-1,-1],[1,-1],[1,1],[-1,1],[-1,-1]]]}'),]);
268+
269+
Place::query()
270+
->whereContains('area', new Point(0, 0))
271+
->exists(); // true
272+
```
273+
</details>
274+
275+
### whereTouches
276+
277+
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.
278+
279+
| parameter name | type
280+
| ------------------ | --------------------
281+
| `$column` | `string`
282+
| `$geometryOrColumn` | `Geometry \| string`
283+
284+
<details><summary>Example</summary>
285+
286+
```php
287+
Place::create(['location' => new Point(0, 0)]);
288+
289+
Place::query()
290+
->whereTouches('location', Polygon::fromJson('{"type":"Polygon","coordinates":[[[-1,-1],[0,-1],[0,0],[-1,0],[-1,-1]]]}'))
291+
->exists(); // true
292+
```
293+
</details>
294+
295+
### whereIntersects
296+
297+
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.
298+
299+
| parameter name | type
300+
| ------------------ | --------------------
301+
| `$column` | `string`
302+
| `$geometryOrColumn` | `Geometry \| string`
303+
304+
<details><summary>Example</summary>
305+
306+
```php
307+
Place::create(['location' => new Point(0, 0)]);
308+
309+
Place::query()
310+
->whereIntersects('location', Polygon::fromJson('{"type":"Polygon","coordinates":[[[-1,-1],[1,-1],[1,1],[-1,1],[-1,-1]]]}'))
311+
->exists(); // true
312+
```
313+
</details>
314+
315+
### whereCrosses
316+
317+
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.
318+
319+
| parameter name | type
320+
| ------------------ | --------------------
321+
| `$column` | `string`
322+
| `$geometryOrColumn` | `Geometry \| string`
323+
324+
<details><summary>Example</summary>
325+
326+
```php
327+
Place::create(['line_string' => LineString::fromJson('{"type":"LineString","coordinates":[[0,0],[2,0]]}')]);
328+
329+
Place::query()
330+
->whereCrosses('line_string', Polygon::fromJson('{"type":"Polygon","coordinates":[[[-1,-1],[1,-1],[1,1],[-1,1],[-1,-1]]]}'))
331+
->exists(); // true
332+
```
333+
</details>
334+
335+
### whereDisjoint
336+
337+
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.
338+
339+
| parameter name | type
340+
| ------------------ | --------------------
341+
| `$column` | `string`
342+
| `$geometryOrColumn` | `Geometry \| string`
343+
344+
<details><summary>Example</summary>
345+
346+
```php
347+
Place::create(['location' => new Point(0, 0)]);
348+
349+
Place::query()
350+
->whereDisjoint('location', Polygon::fromJson('{"type":"Polygon","coordinates":[[[-1,-1],[-0.5,-1],[-0.5,-0.5],[-1,-0.5],[-1,-1]]]}'))
351+
->exists(); // true
352+
```
353+
</details>
354+
355+
### whereEquals
356+
357+
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.
358+
359+
| parameter name | type
360+
| ------------------ | --------------------
361+
| `$column` | `string`
362+
| `$geometryOrColumn` | `Geometry \| string`
363+
364+
<details><summary>Example</summary>
365+
366+
```php
367+
Place::create(['location' => new Point(0, 0)]);
368+
369+
Place::query()
370+
->whereEquals('location', new Point(0, 0))
371+
->exists(); // true
372+
```
373+
</details>
374+

0 commit comments

Comments
 (0)