feat(#305): add support for PostGIS operators

fixtures/MartinGeorgiev/Doctrine/Entity/ContainsGeometries.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Fixtures\MartinGeorgiev\Doctrine\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use MartinGeorgiev\Doctrine\DBAL\Types\ValueObject\WktSpatialData;
+
+#[ORM\Entity()]
+class ContainsGeometries extends Entity
+{
+    #[ORM\Column(type: 'geometry')]
+    public WktSpatialData $geometry1;
+
+    #[ORM\Column(type: 'geometry')]
+    public WktSpatialData $geometry2;
+
+    #[ORM\Column(type: 'geography')]
+    public WktSpatialData $geography1;
+
+    #[ORM\Column(type: 'geography')]
+    public WktSpatialData $geography2;
+}

src/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/BoundingBoxDistance.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MartinGeorgiev\Doctrine\ORM\Query\AST\Functions;
+
+/**
+ * Implementation of PostGIS 2D bounding box distance operator (using <#>).
+ *
+ * Returns the 2D distance between A and B bounding boxes.
+ * This is useful for index-based distance queries.
+ *
+ * @see https://postgis.net/docs/reference.html#Operators_Distance
+ * @since 3.5
+ *
+ * @author Martin Georgiev <martin.georgiev@gmail.com>
+ *
+ * @example Using it in DQL: "SELECT BOUNDING_BOX_DISTANCE(g1.geometry, g2.geometry) FROM Entity g1, Entity g2"
+ * Returns numeric distance value.
+ */
+class BoundingBoxDistance extends BaseFunction
+{
+    protected function customizeFunction(): void
+    {
+        $this->setFunctionPrototype('(%s <#> %s)');
+        $this->addNodeMapping('StringPrimary');
+        $this->addNodeMapping('StringPrimary');
+    }
+}

src/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/GeometryDistance.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MartinGeorgiev\Doctrine\ORM\Query\AST\Functions;
+
+/**
+ * Implementation of PostGIS 2D distance between geometries operator (using <->).
+ *
+ * Returns the 2D distance between A and B geometries.
+ * This differs from BoundingBoxDistance (using <#>), which measures distance between
+ * bounding boxes only. The <-> operator is commonly used for KNN nearest-neighbor
+ * ordering, and on PostgreSQL 9.5+ with PostGIS 2.2+ it returns true geometry distance;
+ * on older stacks it behaved as a centroid-of-bounding-box distance approximation.
+ *
+ * @see https://postgis.net/docs/reference.html#Operators
+ * @see https://postgis.net/docs/geometry_distance_knn.html
+ * @since 3.5
+ *
+ * @author Martin Georgiev <martin.georgiev@gmail.com>
+ *
+ * @example Using it in DQL: "SELECT GEOMETRY_DISTANCE(g1.geometry, g2.geometry) FROM Entity g1, Entity g2"
+ * Returns numeric distance value.
+ */
+class GeometryDistance extends BaseFunction
+{
+    protected function customizeFunction(): void
+    {
+        $this->setFunctionPrototype('(%s <-> %s)');
+        $this->addNodeMapping('StringPrimary');
+        $this->addNodeMapping('StringPrimary');
+    }
+}

src/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/NDimensionalBoundingBoxDistance.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MartinGeorgiev\Doctrine\ORM\Query\AST\Functions;
+
+/**
+ * Implementation of PostGIS n-D bounding box distance operator (using <<#>>).
+ *
+ * Returns the n-D distance between A and B bounding boxes.
+ * This operator works with multi-dimensional geometries.
+ *
+ * @see https://postgis.net/docs/reference.html#Operators_Distance
+ * @since 3.5
+ *
+ * @author Martin Georgiev <martin.georgiev@gmail.com>
+ *
+ * @example Using it in DQL: "SELECT ND_BOUNDING_BOX_DISTANCE(g1.geometry, g2.geometry) FROM Entity g1, Entity g2"
+ * Returns numeric distance value.
+ */
+class NDimensionalBoundingBoxDistance extends BaseFunction
+{
+    protected function customizeFunction(): void
+    {
+        $this->setFunctionPrototype('(%s <<#>> %s)');
+        $this->addNodeMapping('StringPrimary');
+        $this->addNodeMapping('StringPrimary');
+    }
+}

src/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/NDimensionalCentroidDistance.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MartinGeorgiev\Doctrine\ORM\Query\AST\Functions;
+
+/**
+ * Implementation of PostGIS n-D centroid distance operator (using <<->>).
+ *
+ * Returns the n-D distance between the centroids of A and B bounding boxes.
+ * This operator works with multi-dimensional geometries.
+ *
+ * @see https://postgis.net/docs/reference.html#Operators_Distance
+ * @since 3.5
+ *
+ * @author Martin Georgiev <martin.georgiev@gmail.com>
+ *
+ * @example Using it in DQL: "SELECT ND_CENTROID_DISTANCE(g1.geometry, g2.geometry) FROM Entity g1, Entity g2"
+ * Returns numeric distance value.
+ */
+class NDimensionalCentroidDistance extends BaseFunction
+{
+    protected function customizeFunction(): void
+    {
+        $this->setFunctionPrototype('(%s <<->> %s)');
+        $this->addNodeMapping('StringPrimary');
+        $this->addNodeMapping('StringPrimary');
+    }
+}

src/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/NDimensionalOverlaps.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MartinGeorgiev\Doctrine\ORM\Query\AST\Functions;
+
+/**
+ * Implementation of PostGIS n-dimensional bounding box intersects operator (using &&&).
+ *
+ * Returns TRUE if A's n-D bounding box intersects B's n-D bounding box.
+ * This operator works with 3D and higher dimensional geometries.
+ *
+ * @see https://postgis.net/docs/reference.html#Operators_Geometry
+ * @since 3.5
+ *
+ * @author Martin Georgiev <martin.georgiev@gmail.com>
+ *
+ * @example Using it in DQL with boolean comparison: "WHERE ND_OVERLAPS(g1.geometry, g2.geometry) = TRUE"
+ * Returns boolean, must be used with "= TRUE" or "= FALSE" in DQL.
+ */
+class NDimensionalOverlaps extends BaseFunction
+{
+    protected function customizeFunction(): void
+    {
+        $this->setFunctionPrototype('(%s &&& %s)');
+        $this->addNodeMapping('StringPrimary');
+        $this->addNodeMapping('StringPrimary');
+    }
+}

src/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/OverlapsAbove.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MartinGeorgiev\Doctrine\ORM\Query\AST\Functions;
+
+/**
+ * Implementation of PostGIS bounding box overlaps or is above operator (using |&>).
+ *
+ * Returns TRUE if A's bounding box overlaps or is above B's.
+ *
+ * @see https://postgis.net/docs/reference.html#Operators_Geometry
+ * @since 3.5
+ *
+ * @author Martin Georgiev <martin.georgiev@gmail.com>
+ *
+ * @example Using it in DQL with boolean comparison: "WHERE OVERLAPS_ABOVE(g1.geometry, g2.geometry) = TRUE"
+ * Returns boolean, must be used with "= TRUE" or "= FALSE" in DQL.
+ */
+class OverlapsAbove extends BaseFunction
+{
+    protected function customizeFunction(): void
+    {
+        $this->setFunctionPrototype('(%s |&> %s)');
+        $this->addNodeMapping('StringPrimary');
+        $this->addNodeMapping('StringPrimary');
+    }
+}

src/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/OverlapsBelow.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MartinGeorgiev\Doctrine\ORM\Query\AST\Functions;
+
+/**
+ * Implementation of PostGIS bounding box overlaps or is below operator (using &<|).
+ *
+ * Returns TRUE if A's bounding box overlaps or is below B's.
+ *
+ * @see https://postgis.net/docs/reference.html#Operators_Geometry
+ * @since 3.5
+ *
+ * @author Martin Georgiev <martin.georgiev@gmail.com>
+ *
+ * @example Using it in DQL with boolean comparison: "WHERE OVERLAPS_BELOW(g1.geometry, g2.geometry) = TRUE"
+ * Returns boolean, must be used with "= TRUE" or "= FALSE" in DQL.
+ */
+class OverlapsBelow extends BaseFunction
+{
+    protected function customizeFunction(): void
+    {
+        $this->setFunctionPrototype('(%s &<| %s)');
+        $this->addNodeMapping('StringPrimary');
+        $this->addNodeMapping('StringPrimary');
+    }
+}

src/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/OverlapsLeft.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MartinGeorgiev\Doctrine\ORM\Query\AST\Functions;
+
+/**
+ * Implementation of PostGIS bounding box overlaps or is to the left operator (using &<).
+ *
+ * Returns TRUE if A's bounding box overlaps or is to the left of B's.
+ *
+ * @see https://postgis.net/docs/reference.html#Operators_Geometry
+ * @since 3.5
+ *
+ * @author Martin Georgiev <martin.georgiev@gmail.com>
+ *
+ * @example Using it in DQL with boolean comparison: "WHERE OVERLAPS_LEFT(g1.geometry, g2.geometry) = TRUE"
+ * Returns boolean, must be used with "= TRUE" or "= FALSE" in DQL.
+ */
+class OverlapsLeft extends BaseFunction
+{
+    protected function customizeFunction(): void
+    {
+        $this->setFunctionPrototype('(%s &< %s)');
+        $this->addNodeMapping('StringPrimary');
+        $this->addNodeMapping('StringPrimary');
+    }
+}

src/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/OverlapsRight.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MartinGeorgiev\Doctrine\ORM\Query\AST\Functions;
+
+/**
+ * Implementation of PostGIS bounding box overlaps or is to the right operator (using &>).
+ *
+ * Returns TRUE if A's bounding box overlaps or is to the right of B's.
+ *
+ * @see https://postgis.net/docs/reference.html#Operators_Geometry
+ * @since 3.5
+ *
+ * @author Martin Georgiev <martin.georgiev@gmail.com>
+ *
+ * @example Using it in DQL with boolean comparison: "WHERE OVERLAPS_RIGHT(g1.geometry, g2.geometry) = TRUE"
+ * Returns boolean, must be used with "= TRUE" or "= FALSE" in DQL.
+ */
+class OverlapsRight extends BaseFunction
+{
+    protected function customizeFunction(): void
+    {
+        $this->setFunctionPrototype('(%s &> %s)');
+        $this->addNodeMapping('StringPrimary');
+        $this->addNodeMapping('StringPrimary');
+    }
+}

src/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/SpatialContainedBy.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MartinGeorgiev\Doctrine\ORM\Query\AST\Functions;
+
+/**
+ * Implementation of PostGIS spatial bounding box contained by operator (using @).
+ *
+ * Returns TRUE if A's bounding box is contained by B's.
+ * This is the spatial version of the @ operator, distinct from the array/JSON version.
+ *
+ * @see https://postgis.net/docs/reference.html#Operators_Geometry
+ * @since 3.5
+ *
+ * @author Martin Georgiev <martin.georgiev@gmail.com>
+ *
+ * @example Using it in DQL with boolean comparison: "WHERE SPATIAL_CONTAINED_BY(g1.geometry, g2.geometry) = TRUE"
+ * Returns boolean, must be used with "= TRUE" or "= FALSE" in DQL.
+ */
+class SpatialContainedBy extends BaseFunction
+{
+    protected function customizeFunction(): void
+    {
+        $this->setFunctionPrototype('(%s @ %s)');
+        $this->addNodeMapping('StringPrimary');
+        $this->addNodeMapping('StringPrimary');
+    }
+}

src/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/SpatialContains.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MartinGeorgiev\Doctrine\ORM\Query\AST\Functions;
+
+/**
+ * Implementation of PostGIS spatial bounding box contains operator (using ~).
+ *
+ * Returns TRUE if A's bounding box contains B's.
+ * This is the spatial version of the ~ operator, distinct from the array/JSON version.
+ *
+ * @see https://postgis.net/docs/reference.html#Operators_Geometry
+ * @since 3.5
+ *
+ * @author Martin Georgiev <martin.georgiev@gmail.com>
+ *
+ * @example Using it in DQL with boolean comparison: "WHERE SPATIAL_CONTAINS(g1.geometry, g2.geometry) = TRUE"
+ * Returns boolean, must be used with "= TRUE" or "= FALSE" in DQL.
+ */
+class SpatialContains extends BaseFunction
+{
+    protected function customizeFunction(): void
+    {
+        $this->setFunctionPrototype('(%s ~ %s)');
+        $this->addNodeMapping('StringPrimary');
+        $this->addNodeMapping('StringPrimary');
+    }
+}

src/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/SpatialSame.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MartinGeorgiev\Doctrine\ORM\Query\AST\Functions;
+
+/**
+ * Implementation of PostGIS bounding box same as operator (using ~=).
+ *
+ * Returns TRUE if A's bounding box is the same as B's.
+ *
+ * @see https://postgis.net/docs/reference.html#Operators_Geometry
+ * @since 3.5
+ *
+ * @author Martin Georgiev <martin.georgiev@gmail.com>
+ *
+ * @example Using it in DQL with boolean comparison: "WHERE SPATIAL_SAME(g1.geometry, g2.geometry) = TRUE"
+ * Returns boolean, must be used with "= TRUE" or "= FALSE" in DQL.
+ */
+class SpatialSame extends BaseFunction
+{
+    protected function customizeFunction(): void
+    {
+        $this->setFunctionPrototype('(%s ~= %s)');
+        $this->addNodeMapping('StringPrimary');
+        $this->addNodeMapping('StringPrimary');
+    }
+}