Merge pull request #120 from clickbar/geometry-cast-expressions

[2.x] Refactor to remove GeometryType enum

CHANGELOG.md

@@ -14,18 +14,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Removed `GeometryWKBCast`
 - Removed automatic SRID transformation
 - Removed st prefixed builder functions (e.g. `stSelect`, `stWhere`, ...)
+- Removed `GeometryType` Enum
 
 ### Added
 
 - Added `Castable` to all geometries to use them as casters, instead of the `GeometryWKBCast`
 - Added `Aliased` Expression class as wrapper for `AS` in query selects
 - Added `withMagellanCasts()` as EloquentBuilder macro
+- Added `AsGeometry` and `AsGeography` database expressions
 
 ### Improved
 
 - Validate the structure of Geometry coordinates to be an array in the `GeojsonParser` and fail if not
 - Use of ST functions directly in the Laravel default builder methods
 - Use of ST functions directly in Model::create array
+- Renamed parameters of ST functions that can receive geometry or geography from `$geometry` to `$geometryOrGeography`
+- Geometry & Box implements `Expression` and therefore can be used in `->select(...)` directly now 
 
 ### Removed
 

README.md

@@ -444,6 +444,23 @@ Since we use Laravel Database Expressions for a seamless integration into the de
 //--> leads to SELECT ST_DistanceSphere(<<currentShipPosition, 'location') AS distance_to_ship
 ```
 
+### Geometry or Geography
+Using PostGIS, you will encounter those two types of geometries. Most of the functions in PostGIS are only defined with parameters of the type `Geometry`. But sometimes you explicitly want to add casts to your parameters. Therefore, we added two cast expressions:
+- `Geometry` => `\Clickbar\Magellan\Database\Expressions\AsGeometry` 
+- `Geography` => `\Clickbar\Magellan\Database\Expressions\AsGeography`
+
+Considering we want to buffer the location of our ports by 50 meters. Looking into the PostGIS documentation we can see the following: 
+> For geometry, the distance is specified in the units of the Spatial Reference System of the geometry. For geography, the distance is specified in meters.
+> [https://postgis.net/docs/ST_Buffer.html](https://postgis.net/docs/ST_Buffer.html)
+
+Therefore, we need to cast our points from the location colum to geography before handing them over to the buffer function:
+```php
+$bufferedPorts = Port::query()
+    ->select(new Aliased(ST::buffer(new AsGeography('location'), 50), alias: 'buffered_location'))
+    ->withCasts(['buffered_location' => Polygon::class])
+    ->get();
+```
+
 
 
 ### Autocast for BBox or geometries

src/Data/Boxes/Box.php

@@ -2,11 +2,9 @@
 
 namespace Clickbar\Magellan\Data\Boxes;
 
-use Illuminate\Database\Query\Expression;
+use Illuminate\Contracts\Database\Query\Expression as ExpressionContract;
 
-abstract class Box
+abstract class Box implements ExpressionContract
 {
     abstract public function toString(): string;
-
-    abstract public function toExpression(): Expression;
 }

src/Data/Boxes/Box2D.php

@@ -2,7 +2,7 @@
 
 namespace Clickbar\Magellan\Data\Boxes;
 
-use Illuminate\Database\Query\Expression;
+use Illuminate\Database\Grammar;
 
 class Box2D extends Box
 {
@@ -40,8 +40,8 @@ public function toString(): string
         return "BOX({$this->xMin} {$this->yMin},{$this->xMax} {$this->yMax})";
     }
 
-    public function toExpression(): Expression
+    public function getValue(Grammar $grammar): string
     {
-        return new Expression("'{$this->toString()}'::box2d");
+        return $grammar->quoteString($this->toString()).'::box2d';
     }
 }

src/Data/Boxes/Box3D.php

@@ -2,7 +2,7 @@
 
 namespace Clickbar\Magellan\Data\Boxes;
 
-use Illuminate\Database\Query\Expression;
+use Illuminate\Database\Grammar;
 
 class Box3D extends Box
 {
@@ -50,8 +50,8 @@ public function toString(): string
         return "BOX3D({$this->xMin} {$this->yMin} {$this->zMin},{$this->xMax} {$this->yMax} {$this->zMax})";
     }
 
-    public function toExpression(): Expression
+    public function getValue(Grammar $grammar): string
     {
-        return new Expression("'{$this->toString()}'::box3d");
+        return $grammar->quoteString($this->toString()).'::box3d';
     }
 }

src/Data/Geometries/Geometry.php

@@ -3,11 +3,14 @@
 namespace Clickbar\Magellan\Data\Geometries;
 
 use Clickbar\Magellan\Cast\GeometryCast;
+use Clickbar\Magellan\IO\Generator\WKT\WKTGenerator;
 use Illuminate\Contracts\Database\Eloquent\Castable;
+use Illuminate\Contracts\Database\Query\Expression;
+use Illuminate\Database\Grammar;
 use Illuminate\Support\Facades\Config;
 use JsonSerializable;
 
-abstract class Geometry implements \Stringable, Castable, GeometryInterface, JsonSerializable
+abstract class Geometry implements \Stringable, Castable, Expression, GeometryInterface, JsonSerializable
 {
     public function __construct(
         protected ?int $srid = null,
@@ -60,4 +63,12 @@ public static function castUsing(array $arguments): GeometryCast
 
         return new GeometryCast($class);
     }
+
+    public function getValue(Grammar $grammar): string
+    {
+        $generatorClass = Config::get('magellan.sql_generator', WKTGenerator::class);
+        $generator = new $generatorClass();
+
+        return $generator->toPostgisGeometrySql($this, Config::get('magellan.schema'));
+    }
 }

src/Database/Builder/StringifiesQueryParameters.php

@@ -0,0 +1,62 @@
+<?php
+
+namespace Clickbar\Magellan\Database\Builder;
+
+use Clickbar\Magellan\Database\MagellanExpressions\ColumnParameter;
+use Closure;
+use Illuminate\Contracts\Database\Query\Expression;
+use Illuminate\Database\Eloquent\Builder as EloquentBuilder;
+use Illuminate\Database\Eloquent\Relations\Relation;
+use Illuminate\Database\Grammar;
+use Illuminate\Database\Query\Builder;
+use Illuminate\Support\Facades\DB;
+
+trait StringifiesQueryParameters
+{
+    public function stringifyQueryParameter(Grammar $grammar, mixed $param): string
+    {
+
+        // 1. Check if param is queryable -> it's a subquery
+        if ($this->isQueryable($param)) {
+            // --> Create sub and replace with param array
+            return $this->createSub($param);
+        }
+
+        // 2. Basic Binding Value
+        if ($param instanceof ValueParameter) {
+            // --> escape and replace
+            return $grammar->escape($param->getValue());
+        }
+
+        // 3. expression
+        if ($param instanceof Expression) {
+            return $param->getValue($grammar);
+        }
+
+        // 4. Column Parameter
+        if ($param instanceof ColumnParameter) {
+            return $grammar->wrap($param->getValue());
+        }
+
+        // 5. string / default
+        return $grammar->wrap($param);
+    }
+
+    private function createSub($query): string
+    {
+        if ($query instanceof Closure) {
+            $callback = $query;
+            $callback($query = DB::query());
+        }
+
+        return "({$query->toRawSql()})";
+    }
+
+    private function isQueryable($value): bool
+    {
+        return $value instanceof Builder ||
+            $value instanceof EloquentBuilder ||
+            $value instanceof Relation ||
+            $value instanceof Closure;
+    }
+}

src/Database/Builder/BindingExpression.php → src/Database/Builder/ValueParameter.php

@@ -2,7 +2,7 @@
 
 namespace Clickbar\Magellan\Database\Builder;
 
-class BindingExpression
+class ValueParameter
 {
     public function __construct(protected mixed $value)
     {

src/Database/Expressions/AsGeography.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Clickbar\Magellan\Database\Expressions;
+
+use Closure;
+use Illuminate\Contracts\Database\Query\Expression as ExpressionContract;
+use Illuminate\Database\Grammar;
+
+class AsGeography extends GeometryWrapperExpression
+{
+    public function __construct(
+        public string|ExpressionContract|Closure $expression,
+    ) {
+    }
+
+    public function getValue(Grammar $grammar): string
+    {
+        $expression = $this->stringifyQueryParameter($grammar, $this->expression);
+
+        return "($expression)::geography";
+    }
+}

src/Database/Expressions/AsGeometry.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Clickbar\Magellan\Database\Expressions;
+
+use Closure;
+use Illuminate\Contracts\Database\Query\Expression as ExpressionContract;
+use Illuminate\Database\Grammar;
+
+class AsGeometry extends GeometryWrapperExpression
+{
+    public function __construct(
+        public string|ExpressionContract|Closure $expression,
+    ) {
+    }
+
+    public function getValue(Grammar $grammar): string
+    {
+        $expression = $this->stringifyQueryParameter($grammar, $this->expression);
+
+        return "($expression)::geometry";
+    }
+}

src/Database/Expressions/GeometryWrapperExpression.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Clickbar\Magellan\Database\Expressions;
+
+use Clickbar\Magellan\Database\Builder\StringifiesQueryParameters;
+use Illuminate\Contracts\Database\Query\Expression;
+
+abstract class GeometryWrapperExpression implements Expression
+{
+    use StringifiesQueryParameters;
+}

src/Database/MagellanExpressions/ColumnParameter.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace Clickbar\Magellan\Database\MagellanExpressions;
+
+/**
+ * @internal
+ *
+ * Wrapper class for the parameters that represents a database column.
+ * We need this wrapper to distinguish when generating the actual SQL of a MagellanBaseExpression.
+ */
+class ColumnParameter
+{
+    protected function __construct(
+        protected readonly string $column,
+    ) {
+    }
+
+    /**
+     * Only wrap the given value into the ColumnParameter if it is string.
+     *
+     * @return self|mixed
+     */
+    public static function wrap(mixed $value): mixed
+    {
+        if (is_string($value)) {
+            return new self($value);
+        }
+
+        return $value;
+    }
+
+    public function getValue(): string
+    {
+        return $this->column;
+    }
+}