Add convex hull query

Author: Riley19280

API.md

@@ -441,3 +441,27 @@ Place::query()
     ->exists(); // true
 ```
 </details>
+
+## Available Spatial Queries
+
+###  convexHull
+
+Creates a ConvexHull using the specified geometry using the [ST_ConvexHull](https://dev.mysql.com/doc/refman/8.0/en/spatial-operator-functions.html#function_st-convexhull) function.
+
+| parameter name | type                |
+|----------------|---------------------|
+| `$geometry`    | `Geometry \ string` |
+
+<details><summary>Example</summary>
+
+```php
+$points = MultiPoint::fromJson('{"type":"MultiPoint","coordinates":[[-1,-1],[1,-1],[1,1],[-1,1],[-1,-1],[0,0]]}');
+
+$wkbHull = SpatialQuery::make()
+  ->convexHull($points)
+  ->first()
+  ->convex_hull;
+  
+Polygon::fromWkb($wkbHull) // {"type":"Polygon","coordinates":[[[-1,-1],[1,-1],[1,1],[-1,1],[-1,-1]]]}
+```
+</details>

src/SpatialBuilder.php

@@ -6,7 +6,6 @@
 
 use Illuminate\Contracts\Database\Query\Expression as ExpressionContract;
 use Illuminate\Database\Eloquent\Builder;
-use Illuminate\Support\Facades\DB;
 use MatanYadaev\EloquentSpatial\Objects\Geometry;
 
 /**
@@ -18,6 +17,8 @@
  */
 class SpatialBuilder extends Builder
 {
+  use SpatialQueryHelpers;
+
   public function withDistance(
     ExpressionContract|Geometry|string $column,
     ExpressionContract|Geometry|string $geometryOrColumn,
@@ -315,19 +316,4 @@ public function whereSrid(
 
     return $this;
   }
-
-  protected function toExpressionString(ExpressionContract|Geometry|string $geometryOrColumnOrExpression): string
-  {
-    $grammar = $this->getGrammar();
-
-    if ($geometryOrColumnOrExpression instanceof ExpressionContract) {
-      $expression = $geometryOrColumnOrExpression;
-    } elseif ($geometryOrColumnOrExpression instanceof Geometry) {
-      $expression = $geometryOrColumnOrExpression->toSqlExpression($this->getConnection());
-    } else {
-      $expression = DB::raw($grammar->wrap($geometryOrColumnOrExpression));
-    }
-
-    return (string) $expression->getValue($grammar);
-  }
 }

src/SpatialQuery.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace MatanYadaev\EloquentSpatial;
+
+use Illuminate\Contracts\Database\Query\Expression as ExpressionContract;
+use Illuminate\Database\ConnectionInterface;
+use Illuminate\Database\Query\Builder;
+use Illuminate\Database\Query\Grammars\Grammar;
+use Illuminate\Database\Query\Processors\Processor;
+use Illuminate\Support\Facades\DB;
+use MatanYadaev\EloquentSpatial\Objects\Geometry;
+
+class SpatialQuery extends Builder
+{
+  use SpatialQueryHelpers;
+
+  public function __construct(ConnectionInterface $connection = null, Grammar $grammar = null, Processor $processor = null)
+  {
+    parent::__construct($connection ?? DB::connection(), $grammar, $processor);
+  }
+
+  public static function make(ConnectionInterface $connection = null, Grammar $grammar = null, Processor $processor = null): self
+  {
+    return new self($connection, $grammar, $processor);
+  }
+
+  public function convexHull(
+    ExpressionContract|Geometry|string $geometry,
+  ): self
+  {
+    $this->selectRaw(
+      sprintf(
+        'ST_CONVEXHULL(%s) as convex_hull',
+        $this->toExpressionString($geometry),
+      )
+    );
+
+    return $this;
+  }
+}

src/SpatialQueryHelpers.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace MatanYadaev\EloquentSpatial;
+
+use Illuminate\Contracts\Database\Query\Expression as ExpressionContract;
+use Illuminate\Support\Facades\DB;
+use MatanYadaev\EloquentSpatial\Objects\Geometry;
+
+trait SpatialQueryHelpers
+{
+  protected function toExpressionString(ExpressionContract|Geometry|string $geometryOrColumnOrExpression): string
+  {
+    $grammar = $this->getGrammar();
+
+    if ($geometryOrColumnOrExpression instanceof ExpressionContract) {
+      $expression = $geometryOrColumnOrExpression;
+    } elseif ($geometryOrColumnOrExpression instanceof Geometry) {
+      $expression = $geometryOrColumnOrExpression->toSqlExpression($this->getConnection());
+    } else {
+      $expression = DB::raw($grammar->wrap($geometryOrColumnOrExpression));
+    }
+
+    return (string) $expression->getValue($grammar);
+  }
+}

tests/SpatialBuilderTest.php

@@ -408,34 +408,3 @@
 
   expect($testPlaceWithDistance)->not()->toBeNull();
 });
-
-it('toExpressionString can handle a Expression input', function (): void {
-  $spatialBuilder = TestPlace::query();
-  $toExpressionStringMethod = (new ReflectionClass($spatialBuilder))->getMethod('toExpressionString');
-
-  $result = $toExpressionStringMethod->invoke($spatialBuilder, DB::raw('POINT(longitude, latitude)'));
-
-  expect($result)->toBe('POINT(longitude, latitude)');
-});
-
-it('toExpressionString can handle a Geometry input', function (): void {
-  $spatialBuilder = TestPlace::query();
-  $toExpressionStringMethod = (new ReflectionClass($spatialBuilder))->getMethod('toExpressionString');
-  $polygon = Polygon::fromJson('{"type":"Polygon","coordinates":[[[-1,-1],[1,-1],[1,1],[-1,1],[-1,-1]]]}');
-
-  $result = $toExpressionStringMethod->invoke($spatialBuilder, $polygon);
-
-  $grammar = $spatialBuilder->getGrammar();
-  $connection = $spatialBuilder->getConnection();
-  $sqlSerializedPolygon = $polygon->toSqlExpression($connection)->getValue($grammar);
-  expect($result)->toBe($sqlSerializedPolygon);
-});
-
-it('toExpressionString can handle a string input', function (): void {
-  $spatialBuilder = TestPlace::query();
-  $toExpressionStringMethod = (new ReflectionClass($spatialBuilder))->getMethod('toExpressionString');
-
-  $result = $toExpressionStringMethod->invoke($spatialBuilder, 'test_places.point');
-
-  expect($result)->toBe('`test_places`.`point`');
-});

tests/SpatialQueryHelpersTest.php

@@ -0,0 +1,35 @@
+<?php
+
+use MatanYadaev\EloquentSpatial\Objects\Polygon;
+use MatanYadaev\EloquentSpatial\Tests\TestModels\TestPlace;
+
+it('toExpressionString can handle a Expression input', function (): void {
+  $spatialBuilder = TestPlace::query();
+  $toExpressionStringMethod = (new ReflectionClass($spatialBuilder))->getMethod('toExpressionString');
+
+  $result = $toExpressionStringMethod->invoke($spatialBuilder, DB::raw('POINT(longitude, latitude)'));
+
+  expect($result)->toBe('POINT(longitude, latitude)');
+});
+
+it('toExpressionString can handle a Geometry input', function (): void {
+  $spatialBuilder = TestPlace::query();
+  $toExpressionStringMethod = (new ReflectionClass($spatialBuilder))->getMethod('toExpressionString');
+  $polygon = Polygon::fromJson('{"type":"Polygon","coordinates":[[[-1,-1],[1,-1],[1,1],[-1,1],[-1,-1]]]}');
+
+  $result = $toExpressionStringMethod->invoke($spatialBuilder, $polygon);
+
+  $grammar = $spatialBuilder->getGrammar();
+  $connection = $spatialBuilder->getConnection();
+  $sqlSerializedPolygon = $polygon->toSqlExpression($connection)->getValue($grammar);
+  expect($result)->toBe($sqlSerializedPolygon);
+});
+
+it('toExpressionString can handle a string input', function (): void {
+  $spatialBuilder = TestPlace::query();
+  $toExpressionStringMethod = (new ReflectionClass($spatialBuilder))->getMethod('toExpressionString');
+
+  $result = $toExpressionStringMethod->invoke($spatialBuilder, 'test_places.point');
+
+  expect($result)->toBe('`test_places`.`point`');
+});

tests/SpatialQueryTest.php

@@ -0,0 +1,24 @@
+<?php
+
+use Illuminate\Foundation\Testing\DatabaseMigrations;
+use MatanYadaev\EloquentSpatial\Objects\Polygon;
+use MatanYadaev\EloquentSpatial\SpatialQuery;
+
+uses(DatabaseMigrations::class);
+
+it('creates a convex hull', function (): void {
+  $points = \MatanYadaev\EloquentSpatial\Objects\MultiPoint::fromJson('{"type":"MultiPoint","coordinates":[[-1,-1],[1,-1],[1,1],[-1,1],[-1,-1],[0,0]]}', 0);
+
+  $hull = SpatialQuery::make()
+    ->convexHull($points)
+    ->first();
+
+  // @phpstan-ignore-next-line
+  $returnedPolygon = Polygon::fromWkb($hull->convex_hull)->toArray();
+
+  $expectedPolygon = Polygon::fromJson('{"type":"Polygon","coordinates":[[[-1,-1],[1,-1],[1,1],[-1,1],[-1,-1]]]}')->toArray();
+
+  // Compare coordinates like this to prevent ordering differences between database types/versions
+  // @phpstan-ignore-next-line
+  expect($returnedPolygon['coordinates'][0])->toEqualCanonicalizing($expectedPolygon['coordinates'][0]);
+});