Add whereNotWithin and whereNotContains Builder method (#54)

* add-not-within done

* Two functions added NotWithin and NotContains

* .vscode ignored and unnecessary test point removed

Author: dzhwar-k

.gitignore

@@ -5,3 +5,4 @@ build
 composer.lock
 coverage
 vendor
+.vscode

.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+    "workbench.colorCustomizations": {
+        "activityBar.background": "#293019",
+        "titleBar.activeBackground": "#394324",
+        "titleBar.activeForeground": "#FAFBF7"
+    }
+}

API.md

@@ -58,7 +58,9 @@ echo $geometryCollection[1]->latitude; // 0
 * [whereDistanceSphere](#whereDistanceSphere)
 * [orderByDistanceSphere](#orderByDistanceSphere)
 * [whereWithin](#whereWithin)
+* [whereNotWithin](#whereNotWithin)
 * [whereContains](#whereContains)
+* [whereNotContains](#whereNotContains)
 * [whereTouches](#whereTouches)
 * [whereIntersects](#whereIntersects)
 * [whereCrosses](#whereCrosses)
@@ -258,6 +260,26 @@ Place::query()
 ```
 </details>
 
+###  whereNotWithin
+
+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.
+
+| parameter name      | type                 
+| ------------------  | -------------------- 
+| `$column`           | `string`             
+| `$geometryOrColumn` | `Geometry \| string` 
+
+<details><summary>Example</summary>
+
+```php
+Place::create(['location' => new Point(0, 0, 4326)]);
+
+Place::query()
+    ->whereNotWithin('location', Polygon::fromJson('{"type":"Polygon","coordinates":[[[-1,-1],[1,-1],[1,1],[-1,1],[-1,-1]]]}'))
+    ->exists(); // false
+```
+</details>
+
 ###  whereContains
 
 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.
@@ -278,6 +300,26 @@ Place::query()
 ```
 </details>
 
+###  whereNotContains
+
+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.
+
+| parameter name      | type                 
+| ------------------  | -------------------- 
+| `$column`           | `string`             
+| `$geometryOrColumn` | `Geometry \| string` 
+
+<details><summary>Example</summary>
+
+```php
+Place::create(['area' => Polygon::fromJson('{"type":"Polygon","coordinates":[[[-1,-1],[1,-1],[1,1],[-1,1],[-1,-1]]]}'),]);
+
+Place::query()
+    ->whereNotContains('area', new Point(0, 0, 4326))
+    ->exists(); // false
+```
+</details>
+
 ###  whereTouches
 
 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.

src/SpatialBuilder.php

@@ -151,6 +151,19 @@ public function whereWithin(string $column, Geometry|string $geometryOrColumn):
     return $this;
   }
 
+  public function whereNotWithin(string $column, Geometry|string $geometryOrColumn): self
+  {
+    $this->whereRaw(
+      sprintf(
+        'ST_WITHIN(%s, %s) = 0',
+        "`{$column}`",
+        $this->toExpression($geometryOrColumn),
+      )
+    );
+
+    return $this;
+  }
+
   public function whereContains(string $column, Geometry|string $geometryOrColumn): self
   {
     $this->whereRaw(
@@ -164,6 +177,19 @@ public function whereContains(string $column, Geometry|string $geometryOrColumn)
     return $this;
   }
 
+  public function whereNotContains(string $column, Geometry|string $geometryOrColumn): self
+  {
+    $this->whereRaw(
+      sprintf(
+        'ST_CONTAINS(%s, %s) = 0',
+        "`{$column}`",
+        $this->toExpression($geometryOrColumn),
+      )
+    );
+
+    return $this;
+  }
+
   public function whereTouches(string $column, Geometry|string $geometryOrColumn): self
   {
     $this->whereRaw(

tests/SpatialBuilderTest.php

@@ -232,6 +232,21 @@
   expect($testPlacesWithinPolygon[0]->point)->toEqual($pointWithinPolygon);
 });
 
+it('filters by not within', function (): void {
+  $polygon = Polygon::fromJson('{"type":"Polygon","coordinates":[[[-1,-1],[1,-1],[1,1],[-1,1],[-1,-1]]]}', 4326);
+  $pointWithinPolygon = new Point(0, 0, 4326);
+  $pointOutsidePolygon = new Point(50, 50, 4326);
+  TestPlace::factory()->create(['point' => $pointWithinPolygon]);
+  TestPlace::factory()->create(['point' => $pointOutsidePolygon]);
+
+  /** @var TestPlace[] $testPlacesNotWithinPolygon */
+  $testPlacesNotWithinPolygon = TestPlace::query()
+    ->whereNotWithin('point', $polygon)
+    ->get();
+
+  expect($testPlacesNotWithinPolygon)->toHaveCount(1);
+});
+
 it('filters by contains', function (): void {
   $polygon = Polygon::fromJson('{"type":"Polygon","coordinates":[[[-1,-1],[1,-1],[1,1],[-1,1],[-1,-1]]]}', 4326);
   $pointWithinPolygon = new Point(0, 0, 4326);
@@ -249,6 +264,23 @@
   expect($testPlace2)->toBeNull();
 });
 
+it('filters by not contains', function (): void {
+  $polygon = Polygon::fromJson('{"type":"Polygon","coordinates":[[[-1,-1],[1,-1],[1,1],[-1,1],[-1,-1]]]}', 4326);
+  $pointWithinPolygon = new Point(0, 0, 4326);
+  $pointOutsidePolygon = new Point(50, 50, 4326);
+  TestPlace::factory()->create(['polygon' => $polygon]);
+
+  $testPlace = TestPlace::query()
+    ->whereNotContains('polygon', $pointWithinPolygon)
+    ->first();
+  $testPlace2 = TestPlace::query()
+    ->whereNotContains('polygon', $pointOutsidePolygon)
+    ->first();
+
+  expect($testPlace)->toBeNull();
+  expect($testPlace2)->not->toBeNull();
+});
+
 it('filters by touches', function (): void {
   $polygon = Polygon::fromJson('{"type":"Polygon","coordinates":[[[-1,-1],[0,-1],[0,0],[-1,0],[-1,-1]]]}', 4326);
   $pointTouchesPolygon = new Point(0, 0, 4326);