feat: add support for distance operator <@>

Author: seb-jean

docs/AVAILABLE-FUNCTIONS-AND-OPERATORS.md

@@ -23,6 +23,7 @@
 | !~* | NOT_IREGEXP | `MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\NotIRegexp` |
 | @@ | TSMATCH | `MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\Tsmatch` |
 | \|\| | STRCONCAT | `MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\StrConcat` |
+| <@> | DISTANCE | `MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\Distance` |
 
 # Available functions
 

docs/INTEGRATING-WITH-DOCTRINE.md

@@ -164,6 +164,7 @@ $configuration->addCustomStringFunction('REGEXP_MATCH', MartinGeorgiev\Doctrine\
 $configuration->addCustomStringFunction('STRCONCAT', MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\StrConcat::class);
 $configuration->addCustomStringFunction('REGEXP_REPLACE', MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\RegexpReplace::class);
 $configuration->addCustomStringFunction('ROW', MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\Row::class);
+$configuration->addCustomStringFunction('DISTANCE', MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\Distance::class);
 
 # aggregation functions
 $configuration->addCustomStringFunction('ARRAY_AGG', MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\ArrayAgg::class);

docs/INTEGRATING-WITH-LARAVEL.md

@@ -216,6 +216,7 @@ return [
         'REGEXP_SUBSTR' => MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\RegexpSubstr::class,
         'STRCONCAT' => MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\StrConcat::class, // the `||` operator
         'ROW' => MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\Row::class,
+        'DISTANCE' => MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\Distance::class,
 
         # aggregation functions
         'ARRAY_AGG' => MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\ArrayAgg::class,
@@ -224,7 +225,6 @@ return [
         'JSONB_AGG' => MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\JsonbAgg::class,
         'JSONB_OBJECT_AGG' => MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\JsonbObjectAgg::class,
         'STRING_AGG' => MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\StringAgg::class,
-        'XML_AGG' => MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\XmlAgg::class,
     ],
 
     ...

docs/INTEGRATING-WITH-SYMFONY.md

@@ -28,6 +28,7 @@ doctrine:
             inet[]: MartinGeorgiev\Doctrine\DBAL\Types\InetArray
             macaddr: MartinGeorgiev\Doctrine\DBAL\Types\Macaddr
             macaddr[]: MartinGeorgiev\Doctrine\DBAL\Types\MacaddrArray
+
             point: MartinGeorgiev\Doctrine\DBAL\Types\Point
             point[]: MartinGeorgiev\Doctrine\DBAL\Types\PointArray
 ```
@@ -211,6 +212,7 @@ doctrine:
                         REGEXP_SUBSTR: MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\RegexpSubstr
                         ROW: MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\Row
                         STRCONCAT: MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\StrConcat
+                        DISTANCE: MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\Distance
 
                         # aggregation functions
                         ARRAY_AGG: MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\ArrayAgg

fixtures/MartinGeorgiev/Doctrine/Entity/ContainsPoints.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Fixtures\MartinGeorgiev\Doctrine\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use MartinGeorgiev\Doctrine\DBAL\Types\ValueObject\Point;
+
+#[ORM\Entity()]
+class ContainsPoints extends Entity
+{
+    #[ORM\Column(type: 'point')]
+    public Point $point;
+}

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

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MartinGeorgiev\Doctrine\ORM\Query\AST\Functions;
+
+/**
+ * Implementation of PostgreSQL's distance operator (using `<@>`).
+ *
+ * @see https://www.postgresql.org/docs/17/earthdistance.html#EARTHDISTANCE-POINT-BASED
+ * @since 3.1
+ *
+ * @author Sébastien Jean <sebastien.jean76@gmail.com>
+ */
+class Distance extends BaseFunction
+{
+    protected function customizeFunction(): void
+    {
+        $this->setFunctionPrototype('(%s <@> %s)');
+        $this->addNodeMapping('StringPrimary');
+        $this->addNodeMapping('StringPrimary');
+    }
+}

tests/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/DistanceTest.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\MartinGeorgiev\Doctrine\ORM\Query\AST\Functions;
+
+use Fixtures\MartinGeorgiev\Doctrine\Entity\ContainsPoints;
+use MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\Distance;
+
+class DistanceTest extends TestCase
+{
+    protected function getStringFunctions(): array
+    {
+        return [
+            'DISTANCE' => Distance::class,
+        ];
+    }
+
+    protected function getExpectedSqlStatements(): array
+    {
+        return [
+            "SELECT (c0_.point <@> '(2.320041, 48.858889)') AS sclr_0 FROM ContainsPoints c0_",
+        ];
+    }
+
+    protected function getDqlStatements(): array
+    {
+        return [
+            \sprintf("SELECT DISTANCE(e.point, '(2.320041, 48.858889)') FROM %s e", ContainsPoints::class),
+        ];
+    }
+}