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,29 @@
+<?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 is different from the existing Distance class which uses <@> for point distance.
+ *
+ * @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 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/StrictlyAbove.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MartinGeorgiev\Doctrine\ORM\Query\AST\Functions;
+
+/**
+ * Implementation of PostGIS bounding box strictly above operator (using |>>).
+ *
+ * Returns TRUE if A's bounding box is strictly 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 STRICTLY_ABOVE(g1.geometry, g2.geometry) = TRUE"
+ * Returns boolean, must be used with "= TRUE" or "= FALSE" in DQL.
+ */
+class StrictlyAbove extends BaseFunction
+{
+    protected function customizeFunction(): void
+    {
+        $this->setFunctionPrototype('(%s |>> %s)');
+        $this->addNodeMapping('StringPrimary');
+        $this->addNodeMapping('StringPrimary');
+    }
+}

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

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MartinGeorgiev\Doctrine\ORM\Query\AST\Functions;
+
+/**
+ * Implementation of PostGIS bounding box strictly below operator (using <<|).
+ *
+ * Returns TRUE if A's bounding box is strictly 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 STRICTLY_BELOW(g1.geometry, g2.geometry) = TRUE"
+ * Returns boolean, must be used with "= TRUE" or "= FALSE" in DQL.
+ */
+class StrictlyBelow extends BaseFunction
+{
+    protected function customizeFunction(): void
+    {
+        $this->setFunctionPrototype('(%s <<| %s)');
+        $this->addNodeMapping('StringPrimary');
+        $this->addNodeMapping('StringPrimary');
+    }
+}

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

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MartinGeorgiev\Doctrine\ORM\Query\AST\Functions;
+
+/**
+ * Implementation of PostGIS bounding box strictly to the left operator (using <<).
+ *
+ * Returns TRUE if A's bounding box is strictly 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 STRICTLY_LEFT(g1.geometry, g2.geometry) = TRUE"
+ * Returns boolean, must be used with "= TRUE" or "= FALSE" in DQL.
+ */
+class StrictlyLeft extends BaseFunction
+{
+    protected function customizeFunction(): void
+    {
+        $this->setFunctionPrototype('(%s << %s)');
+        $this->addNodeMapping('StringPrimary');
+        $this->addNodeMapping('StringPrimary');
+    }
+}