Skip to content

Commit c47462d

Browse files
MatanYadaevMatanYadaev
committed
wip
1 parent 8b339d1 commit c47462d

File tree

1 file changed

+134
-17
lines changed

1 file changed

+134
-17
lines changed

‎API.md‎

Lines changed: 134 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -27,9 +27,16 @@ Geometry collection functions:
2727

2828
## Available spatial scopes
2929

30+
* [withDistance](#withDistance)
31+
* [whereDistance](#whereDistance)
32+
* [orderByDistance](#orderByDistance)
33+
* [withDistanceSphere](#withDistanceSphere)
34+
* [whereDistanceSphere](#whereDistanceSphere)
35+
* [orderByDistanceSphere](#orderByDistanceSphere)
36+
3037
### withDistance
3138

32-
Retrieves the distance between 2 geometry objects.
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)
3340

3441
| parameter name | type | default |
3542
| ------------------ | -------------------- | ------- |
@@ -40,17 +47,17 @@ Retrieves the distance between 2 geometry objects.
4047
<details><summary>Example</summary>
4148

4249
```php
43-
Place::create(['point' => new Point(0, 0)]);
50+
Place::create(['location' => new Point(0, 0)]);
4451

4552
$placeWithDistance = Place::query()
46-
->withDistance('point', new Point(1, 1))
53+
->withDistance('location', new Point(1, 1))
4754
->first();
4855

4956
echo $placeWithDistance->distance; // 1.4142135623731
5057

5158
// when using alias:
5259
$placeWithDistance = Place::query()
53-
->withDistance('point', new Point(1, 1), 'distance_in_meters')
60+
->withDistance('location', new Point(1, 1), 'distance_in_meters')
5461
->first();
5562

5663
echo $placeWithDistance->distance_in_meters; // 1.4142135623731
@@ -59,36 +66,146 @@ echo $placeWithDistance->distance_in_meters; // 1.4142135623731
5966

6067
### whereDistance
6168

62-
Description
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)
6370

64-
| parameter name | type
71+
| parameter name | type
6572
| ------------------ | --------------------
66-
| `$column` | `string`
73+
| `$column` | `string`
6774
| `$geometryOrColumn` | `Geometry \| string`
6875
| `$operator` | `string`
6976
| `$value` | `int \| float`
7077

7178
<details><summary>Example</summary>
7279

7380
```php
81+
Place::create(['location' => new Point(0, 0)]);
82+
Place::create(['location' => new Point(100, 100)]);
83+
84+
$placesCountWithinDistance = Place::query()
85+
->whereDistance('location', new Point(1, 1), '<', 1.5)
86+
->count();
87+
88+
echo $placesCountWithinDistance; // 1
89+
```
90+
</details>
91+
92+
### orderByDistance
93+
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)
95+
96+
| parameter name | type | default |
97+
| ------------------ | -------------------- | ------- |
98+
| `$column` | `string` |
99+
| `$geometryOrColumn` | `Geometry \| string` |
100+
| `$direction` | `string` | `'asc'`
101+
102+
<details><summary>Example</summary>
103+
104+
```php
105+
Place::create([
106+
'name' => 'first',
107+
'location' => new Point(0, 0),
108+
]);
74109
Place::create([
75-
'name' => 'My place',
76-
'point' => new Point(0, 0),
110+
'name' => 'second',
111+
'location' => new Point(100, 100),
77112
]);
78113

79-
$place = Place::query()
80-
->whereDistance('point', new Point(1, 1), '<', 10)
114+
$places = Place::query()
115+
->orderByDistance('location', new Point(1, 1), 'desc')
116+
->get();
117+
118+
echo $places[0]->name; // second
119+
echo $places[1]->name; // first
120+
```
121+
</details>
122+
123+
### withDistanceSphere
124+
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)
126+
127+
| parameter name | type | default |
128+
| ------------------ | -------------------- | ------- |
129+
| `$column` | `string` |
130+
| `$geometryOrColumn` | `Geometry \| string` |
131+
| `$alias` | `string` | `'distance'`
132+
133+
<details><summary>Example</summary>
134+
135+
```php
136+
Place::create(['location' => new Point(0, 0)]);
137+
138+
$placeWithDistance = Place::query()
139+
->withDistanceSphere('location', new Point(1, 1))
81140
->first();
82141

83-
echo $place->name; // My place
142+
echo $placeWithDistance->distance; // 157249.0357231545
143+
144+
// when using alias:
145+
$placeWithDistance = Place::query()
146+
->withDistanceSphere('location', new Point(1, 1), 'distance_in_meters')
147+
->first();
148+
149+
echo $placeWithDistance->distance_in_meters; // 157249.0357231545
150+
```
151+
</details>
152+
153+
### whereDistance
154+
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)
156+
157+
| parameter name | type
158+
| ------------------ | --------------------
159+
| `$column` | `string`
160+
| `$geometryOrColumn` | `Geometry \| string`
161+
| `$operator` | `string`
162+
| `$value` | `int \| float`
163+
164+
<details><summary>Example</summary>
165+
166+
```php
167+
Place::create(['location' => new Point(0, 0)]);
168+
Place::create(['location' => new Point(100, 100)]);
169+
170+
$placesCountWithinDistance = Place::query()
171+
->whereDistance('location', new Point(1, 1), '<', 160000)
172+
->count();
173+
174+
echo $placesCountWithinDistance; // 1
175+
```
176+
</details>
177+
178+
### orderByDistance
179+
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)
181+
182+
| parameter name | type | default |
183+
| ------------------ | -------------------- | ------- |
184+
| `$column` | `string` |
185+
| `$geometryOrColumn` | `Geometry \| string` |
186+
| `$direction` | `string` | `'asc'`
187+
188+
<details><summary>Example</summary>
189+
190+
```php
191+
Place::create([
192+
'name' => 'first',
193+
'location' => new Point(0, 0),
194+
]);
195+
Place::create([
196+
'name' => 'second',
197+
'location' => new Point(100, 100),
198+
]);
199+
200+
$places = Place::query()
201+
->orderByDistance('location', new Point(1, 1), 'desc')
202+
->get();
203+
204+
echo $places[0]->name; // second
205+
echo $places[1]->name; // first
84206
```
85207
</details>
86208

87-
* `whereDistance(string $column, Geometry | string $geometryOrColumn, string $operator, int | float $distance)`
88-
* `orderByDistance(string $column, Geometry | string $geometryOrColumn, string $direction = 'asc')`
89-
* `withDistanceSphere(string $column, Geometry | string $geometryOrColumn, string $alias = 'distance')`
90-
* `whereDistanceSphere(string $column, Geometry | string $geometryOrColumn, string $operator, int | float $distance)`
91-
* `orderByDistanceSphere(string $column, Geometry | string $geometryOrColumn, string $direction = 'asc')`
92209
* `whereWithin(string $column, Geometry | string $geometryOrColumn)`
93210
* `whereContains(string $column, Geometry | string $geometryOrColumn)`
94211
* `whereTouches(string $column, Geometry | string $geometryOrColumn)`

0 commit comments

Comments
 (0)