feat(#305): add support for PostGIS operators

Author: martin-georgiev

fixtures/MartinGeorgiev/Doctrine/Entity/ContainsGeometries.php

@@ -11,14 +11,14 @@
 class ContainsGeometries extends Entity
 {
     #[ORM\Column(type: 'geometry')]
-    public ?WktSpatialData $geometry1 = null;
+    public WktSpatialData $geometry1;
 
     #[ORM\Column(type: 'geometry')]
-    public ?WktSpatialData $geometry2 = null;
+    public WktSpatialData $geometry2;
 
     #[ORM\Column(type: 'geography')]
-    public ?WktSpatialData $geography1 = null;
+    public WktSpatialData $geography1;
 
     #[ORM\Column(type: 'geography')]
-    public ?WktSpatialData $geography2 = null;
+    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/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');
+    }
+}

src/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/StrictlyRight.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 right operator (using >>).
+ *
+ * Returns TRUE if A's bounding box is strictly 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 STRICTLY_RIGHT(g1.geometry, g2.geometry) = TRUE"
+ * Returns boolean, must be used with "= TRUE" or "= FALSE" in DQL.
+ */
+class StrictlyRight extends BaseFunction
+{
+    protected function customizeFunction(): void
+    {
+        $this->setFunctionPrototype('(%s >> %s)');
+        $this->addNodeMapping('StringPrimary');
+        $this->addNodeMapping('StringPrimary');
+    }
+}

tests/Integration/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/BoundingBoxDistanceTest.php

@@ -0,0 +1,69 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Integration\MartinGeorgiev\Doctrine\ORM\Query\AST\Functions;
+
+use MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\BoundingBoxDistance;
+use PHPUnit\Framework\Attributes\Test;
+
+class BoundingBoxDistanceTest extends SpatialOperatorTestCase
+{
+    protected function getStringFunctions(): array
+    {
+        return [
+            'BOUNDING_BOX_DISTANCE' => BoundingBoxDistance::class,
+        ];
+    }
+
+    #[Test]
+    public function bounding_box_distance_returns_zero_for_identical_geometries(): void
+    {
+        // Identical geometries have zero bounding box distance
+        $dql = "SELECT BOUNDING_BOX_DISTANCE('POINT(1 1)', 'POINT(1 1)') as distance
+                FROM Fixtures\MartinGeorgiev\Doctrine\Entity\ContainsGeometries g
+                WHERE g.id = 1";
+
+        $result = $this->executeDqlQuery($dql);
+        $this->assertEquals(0, $result[0]['distance'], 'Bounding box distance for identical geometries should be 0');
+    }
+
+    #[Test]
+    public function bounding_box_distance_returns_zero_for_overlapping_bounding_boxes(): void
+    {
+        // Overlapping polygons have zero bounding box distance
+        $dql = "SELECT BOUNDING_BOX_DISTANCE('POLYGON((0 0, 2 0, 2 2, 0 2, 0 0))', 'POLYGON((1 1, 3 1, 3 3, 1 3, 1 1))') as distance
+                FROM Fixtures\MartinGeorgiev\Doctrine\Entity\ContainsGeometries g
+                WHERE g.id = 1";
+
+        $result = $this->executeDqlQuery($dql);
+        $this->assertEquals(0, $result[0]['distance'], 'Overlapping bounding boxes should have distance 0');
+    }
+
+    #[Test]
+    public function bounding_box_distance_returns_correct_distance_for_separated_geometries(): void
+    {
+        // Distance between separated points
+        $dql = "SELECT BOUNDING_BOX_DISTANCE('POINT(0 0)', 'POINT(3 4)') as distance
+                FROM Fixtures\MartinGeorgiev\Doctrine\Entity\ContainsGeometries g
+                WHERE g.id = 1";
+
+        $result = $this->executeDqlQuery($dql);
+        $this->assertEquals(5.0, $result[0]['distance'], 'Bounding box distance between (0,0) and (3,4) should be 5');
+    }
+
+    #[Test]
+    public function bounding_box_distance_with_separated_polygons(): void
+    {
+        // Distance between non-overlapping polygons
+        $dql = "SELECT BOUNDING_BOX_DISTANCE('POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))', 'POLYGON((3 3, 4 3, 4 4, 3 4, 3 3))') as distance
+                FROM Fixtures\MartinGeorgiev\Doctrine\Entity\ContainsGeometries g
+                WHERE g.id = 1";
+
+        $result = $this->executeDqlQuery($dql);
+        $this->assertIsNumeric($result[0]['distance']);
+        $this->assertGreaterThan(0, $result[0]['distance']);
+        // Distance should be approximately sqrt((3-1)² + (3-1)²) = sqrt(8) ≈ 2.83
+        $this->assertEqualsWithDelta(2.83, $result[0]['distance'], 0.1, 'Distance between separated polygons');
+    }
+}

tests/Integration/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/GeometryDistanceTest.php

@@ -0,0 +1,82 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Integration\MartinGeorgiev\Doctrine\ORM\Query\AST\Functions;
+
+use MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\GeometryDistance;
+use PHPUnit\Framework\Attributes\Test;
+
+class GeometryDistanceTest extends SpatialOperatorTestCase
+{
+    protected function getStringFunctions(): array
+    {
+        return [
+            'GEOMETRY_DISTANCE' => GeometryDistance::class,
+        ];
+    }
+
+    #[Test]
+    public function geometry_distance_returns_correct_distance_between_test_points(): void
+    {
+        // Distance between POINT(0 0) and POINT(1 1) from test data
+        $dql = 'SELECT GEOMETRY_DISTANCE(g.geometry1, g.geometry2) as distance
+                FROM Fixtures\MartinGeorgiev\Doctrine\Entity\ContainsGeometries g
+                WHERE g.id = 1';
+
+        $result = $this->executeDqlQuery($dql);
+        $this->assertIsNumeric($result[0]['distance']);
+        $this->assertGreaterThan(0, $result[0]['distance']);
+        // Distance between (0,0) and (1,1) should be sqrt(2) ≈ 1.414
+        $this->assertEqualsWithDelta(1.414, $result[0]['distance'], 0.01, 'Distance between (0,0) and (1,1)');
+    }
+
+    #[Test]
+    public function geometry_distance_returns_zero_for_identical_geometries(): void
+    {
+        // Identical geometries should have zero distance
+        $dql = 'SELECT GEOMETRY_DISTANCE(g.geometry1, g.geometry1) as distance
+                FROM Fixtures\MartinGeorgiev\Doctrine\Entity\ContainsGeometries g
+                WHERE g.id = 1';
+
+        $result = $this->executeDqlQuery($dql);
+        $this->assertEquals(0, $result[0]['distance'], 'Distance between identical geometries should be 0');
+    }
+
+    #[Test]
+    public function geometry_distance_with_horizontal_points(): void
+    {
+        // Distance between POINT(0 0) and POINT(5 0) should be 5
+        $dql = "SELECT GEOMETRY_DISTANCE('POINT(0 0)', 'POINT(5 0)') as distance
+                FROM Fixtures\MartinGeorgiev\Doctrine\Entity\ContainsGeometries g
+                WHERE g.id = 1";
+
+        $result = $this->executeDqlQuery($dql);
+        $this->assertEquals(5.0, $result[0]['distance'], 'Horizontal distance should be 5');
+    }
+
+    #[Test]
+    public function geometry_distance_with_vertical_points(): void
+    {
+        // Distance between POINT(0 0) and POINT(0 3) should be 3
+        $dql = "SELECT GEOMETRY_DISTANCE('POINT(0 0)', 'POINT(0 3)') as distance
+                FROM Fixtures\MartinGeorgiev\Doctrine\Entity\ContainsGeometries g
+                WHERE g.id = 1";
+
+        $result = $this->executeDqlQuery($dql);
+        $this->assertEquals(3.0, $result[0]['distance'], 'Vertical distance should be 3');
+    }
+
+    #[Test]
+    public function geometry_distance_with_geography_types(): void
+    {
+        // Geography types should return distance in meters
+        $dql = 'SELECT GEOMETRY_DISTANCE(g.geography1, g.geography2) as distance
+                FROM Fixtures\MartinGeorgiev\Doctrine\Entity\ContainsGeometries g
+                WHERE g.id = 1';
+
+        $result = $this->executeDqlQuery($dql);
+        $this->assertIsNumeric($result[0]['distance']);
+        $this->assertGreaterThan(1000000, $result[0]['distance']); // Lisbon to London is > 1M meters
+    }
+}