feat: add support for array_shuffle() (#324)

Author: martin-georgiev

docs/AVAILABLE-FUNCTIONS-AND-OPERATORS.md

@@ -40,6 +40,7 @@
 | array_prepend | ARRAY_PREPEND | `MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\ArrayPrepend` |
 | array_remove | ARRAY_REMOVE | `MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\ArrayRemove` |
 | array_replace | ARRAY_REPLACE | `MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\ArrayReplace` |
+| array_shuffle | ARRAY_SHUFFLE | `MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\ArrayShuffle` |
 | array_to_json | ARRAY_TO_JSON | `MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\ArrayToJson` |
 | array_to_string | ARRAY_TO_STRING | `MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\ArrayToString` |
 | cardinality | ARRAY_CARDINALITY | `MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\Cardinality` |

docs/INTEGRATING-WITH-LARAVEL.md

@@ -97,6 +97,7 @@ return [
         'ARRAY_PREPEND' => MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\ArrayPrepend::class,
         'ARRAY_REMOVE' => MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\ArrayRemove::class,
         'ARRAY_REPLACE' => MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\ArrayReplace::class,
+        'ARRAY_SHUFFLE' => MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\ArrayShuffle::class,
         'ARRAY_TO_JSON' => MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\ArrayToJson::class,
         'ARRAY_TO_STRING' => MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\ArrayToString::class,
         'SPLIT_PART' => MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\SplitPart::class,

docs/INTEGRATING-WITH-SYMFONY.md

@@ -90,6 +90,7 @@ doctrine:
                         ARRAY_PREPEND: MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\ArrayPrepend
                         ARRAY_REMOVE: MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\ArrayRemove
                         ARRAY_REPLACE: MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\ArrayReplace
+                        ARRAY_SHUFFLE: MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\ArrayShuffle
                         ARRAY_TO_JSON: MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\ArrayToJson
                         ARRAY_TO_STRING: MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\ArrayToString
                         SPLIT_PART: MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\SplitPart

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

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MartinGeorgiev\Doctrine\ORM\Query\AST\Functions;
+
+/**
+ * Implementation of PostgreSQL ARRAY_SHUFFLE().
+ *
+ * @see https://www.postgresql.org/docs/current/functions-array.html
+ * @since 3.0
+ *
+ * @author Martin Georgiev <martin.georgiev@gmail.com>
+ */
+class ArrayShuffle extends BaseFunction
+{
+    protected function customizeFunction(): void
+    {
+        $this->setFunctionPrototype('array_shuffle(%s)');
+        $this->addNodeMapping('StringPrimary');
+    }
+}

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

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\MartinGeorgiev\Doctrine\ORM\Query\AST\Functions;
+
+use Fixtures\MartinGeorgiev\Doctrine\Entity\ContainsArrays;
+use MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\Arr;
+use MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\ArrayShuffle;
+
+class ArrayShuffleTest extends TestCase
+{
+    protected function getStringFunctions(): array
+    {
+        return [
+            'ARRAY_SHUFFLE' => ArrayShuffle::class,
+            'ARRAY' => Arr::class,
+        ];
+    }
+
+    protected function getExpectedSqlStatements(): array
+    {
+        return [
+            'from array field' => 'SELECT array_shuffle(c0_.array1) AS sclr_0 FROM ContainsArrays c0_',
+            'from literal array' => "SELECT array_shuffle(ARRAY['red', 'green', 'blue']) AS sclr_0 FROM ContainsArrays c0_",
+        ];
+    }
+
+    protected function getDqlStatements(): array
+    {
+        return [
+            'from array field' => \sprintf('SELECT ARRAY_SHUFFLE(e.array1) FROM %s e', ContainsArrays::class),
+            'from literal array' => \sprintf("SELECT ARRAY_SHUFFLE(ARRAY('red', 'green', 'blue')) FROM %s e", ContainsArrays::class),
+        ];
+    }
+}