feat: add support for distance operator <@> (#361)

Co-authored-by: Martin Georgiev <martin-georgiev@users.noreply.github.com>

Author: seb-jean

docs/INTEGRATING-WITH-DOCTRINE.md

@@ -163,6 +163,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

@@ -218,6 +218,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,

docs/INTEGRATING-WITH-SYMFONY.md

@@ -212,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,18 @@
+<?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 $point1;
+
+    #[ORM\Column(type: 'point')]
+    public Point $point2;
+}

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/Unit/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/DistanceTest.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Unit\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_.point1 <@> '(2.320041, 48.858889)') AS sclr_0 FROM ContainsPoints c0_",
+            'SELECT (c0_.point1 <@> c0_.point2) AS sclr_0 FROM ContainsPoints c0_',
+            "SELECT ('(1.0, 1.0)' <@> '(2.0, 2.0)') AS sclr_0 FROM ContainsPoints c0_",
+        ];
+    }
+
+    protected function getDqlStatements(): array
+    {
+        return [
+            \sprintf("SELECT DISTANCE(e.point1, '(2.320041, 48.858889)') FROM %s e", ContainsPoints::class),
+            \sprintf('SELECT DISTANCE(e.point1, e.point2) FROM %s e', ContainsPoints::class),
+            \sprintf("SELECT DISTANCE('(1.0, 1.0)', '(2.0, 2.0)') FROM %s e", ContainsPoints::class),
+        ];
+    }
+}