Implement ArrayMergeBuilder, LongestBuilder and ShortestBuilder (#420)

Tigrov · web-flow · commit 320fe4efe83c · 2025-08-21T16:31:52.000+07:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -50,6 +50,7 @@
 - Enh #414: Remove `TableSchema` class and refactor `Schema` class (@Tigrov)
 - Enh #415: Support column's collation (@Tigrov)
 - New #421: Add `Connection::getColumnBuilderClass()` method (@Tigrov)
+- New #420: Implement `ArrayMergeBuilder`, `LongestBuilder` and `ShortestBuilder` classes (@Tigrov)
 
 ## 1.2.0 March 21, 2024
 
diff --git a/psalm.xml b/psalm.xml
@@ -18,5 +18,6 @@
   <issueHandlers>
     <RiskyTruthyFalsyComparison errorLevel="suppress" />
     <MixedAssignment errorLevel="suppress" />
+    <MoreSpecificImplementedParamType errorLevel="suppress" />
   </issueHandlers>
 </psalm>
diff --git a/src/Builder/ArrayMergeBuilder.php b/src/Builder/ArrayMergeBuilder.php
@@ -0,0 +1,76 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Db\Mysql\Builder;
+
+use Yiisoft\Db\Expression\Function\ArrayMerge;
+use Yiisoft\Db\Expression\Function\Builder\MultiOperandFunctionBuilder;
+use Yiisoft\Db\Expression\Function\MultiOperandFunction;
+use Yiisoft\Db\Schema\Column\AbstractArrayColumn;
+use Yiisoft\Db\Schema\Column\ColumnInterface;
+
+use function implode;
+use function is_string;
+use function rtrim;
+
+/**
+ * Builds SQL expressions which merge arrays for {@see ArrayMerge} objects.
+ *
+ * ```sql
+ * (SELECT JSON_ARRAYAGG(value) AS value FROM (
+ *     SELECT value FROM JSON_TABLE(operand1, '$[*]' COLUMNS(value json PATH '$')) AS t
+ *     UNION
+ *     SELECT value FROM JSON_TABLE(operand2, '$[*]' COLUMNS(value json PATH '$')) AS t
+ * ) t)
+ * ```
+ *
+ * @extends MultiOperandFunctionBuilder<ArrayMerge>
+ */
+final class ArrayMergeBuilder extends MultiOperandFunctionBuilder
+{
+    private const DEFAULT_OPERAND_TYPE = 'json';
+
+    /**
+     * Builds a SQL expression which merges arrays from the given {@see ArrayMerge} object.
+     *
+     * @param ArrayMerge $expression The expression to build.
+     * @param array $params The parameters to bind.
+     *
+     * @return string The SQL expression.
+     */
+    protected function buildFromExpression(MultiOperandFunction $expression, array &$params): string
+    {
+        $operandType = $this->buildOperandType($expression->getType());
+        $selects = [];
+
+        foreach ($expression->getOperands() as $operand) {
+            $builtOperand = $this->buildOperand($operand, $params);
+
+            $selects[] = "SELECT value FROM JSON_TABLE($builtOperand, '$[*]' COLUMNS(value $operandType PATH '$')) AS t";
+        }
+
+        return '(SELECT JSON_ARRAYAGG(value) AS value FROM (' . implode(' UNION ', $selects) . ') AS t)';
+    }
+
+    private function buildOperandType(string|ColumnInterface $type): string
+    {
+        if (is_string($type)) {
+            return $type === '' ? self::DEFAULT_OPERAND_TYPE : rtrim($type, '[]');
+        }
+
+        if ($type instanceof AbstractArrayColumn) {
+            if ($type->getDimension() > 1) {
+                return self::DEFAULT_OPERAND_TYPE;
+            }
+
+            $type = $type->getColumn();
+
+            if ($type === null) {
+                return self::DEFAULT_OPERAND_TYPE;
+            }
+        }
+
+        return $this->queryBuilder->getColumnDefinitionBuilder()->buildType($type);
+    }
+}
diff --git a/src/Builder/LongestBuilder.php b/src/Builder/LongestBuilder.php
@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Db\Mysql\Builder;
+
+use Yiisoft\Db\Expression\Function\Builder\MultiOperandFunctionBuilder;
+use Yiisoft\Db\Expression\Function\Longest;
+use Yiisoft\Db\Expression\Function\MultiOperandFunction;
+
+/**
+ * Builds SQL representation of function expressions which returns the longest string from a set of operands.
+ *
+ * ```SQL
+ * (SELECT operand1 AS value
+ * UNION SELECT operand2 AS value
+ * ORDER BY LENGTH(value) DESC LIMIT 1)
+ * ```
+ *
+ * @extends MultiOperandFunctionBuilder<Longest>
+ */
+final class LongestBuilder extends MultiOperandFunctionBuilder
+{
+    /**
+     * Builds a SQL expression to represent the function which returns the longest string.
+     *
+     * @param Longest $expression The expression to build.
+     * @param array $params The parameters to bind.
+     *
+     * @return string The SQL expression.
+     */
+    protected function buildFromExpression(MultiOperandFunction $expression, array &$params): string
+    {
+        $selects = [];
+
+        foreach ($expression->getOperands() as $operand) {
+            $selects[] = 'SELECT ' . $this->buildOperand($operand, $params) . ' AS value';
+        }
+
+        $unions = implode(' UNION ', $selects);
+
+        return "($unions ORDER BY LENGTH(value) DESC LIMIT 1)";
+    }
+}
diff --git a/src/Builder/ShortestBuilder.php b/src/Builder/ShortestBuilder.php
@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Db\Mysql\Builder;
+
+use Yiisoft\Db\Expression\Function\Builder\MultiOperandFunctionBuilder;
+use Yiisoft\Db\Expression\Function\MultiOperandFunction;
+use Yiisoft\Db\Expression\Function\Shortest;
+
+/**
+ * Builds SQL representation of function expressions which return the shortest string from a set of operands.
+ *
+ * ```SQL
+ * (SELECT operand1 AS value
+ * UNION SELECT operand2 AS value
+ * ORDER BY LENGTH(value) ASC LIMIT 1)
+ * ```
+ *
+ * @extends MultiOperandFunctionBuilder<Shortest>
+ */
+final class ShortestBuilder extends MultiOperandFunctionBuilder
+{
+    /**
+     * Builds a SQL expression to represent the function which returns the shortest string.
+     *
+     * @param Shortest $expression The expression to build.
+     * @param array $params The parameters to bind.
+     *
+     * @return string The SQL expression.
+     */
+    protected function buildFromExpression(MultiOperandFunction $expression, array &$params): string
+    {
+        $selects = [];
+
+        foreach ($expression->getOperands() as $operand) {
+            $selects[] = 'SELECT ' . $this->buildOperand($operand, $params) . ' AS value';
+        }
+
+        $unions = implode(' UNION ', $selects);
+
+        return "($unions ORDER BY LENGTH(value) ASC LIMIT 1)";
+    }
+}
diff --git a/src/DQLQueryBuilder.php b/src/DQLQueryBuilder.php
@@ -5,8 +5,14 @@
 namespace Yiisoft\Db\Mysql;
 
 use Yiisoft\Db\Expression\ExpressionInterface;
+use Yiisoft\Db\Expression\Function\ArrayMerge;
+use Yiisoft\Db\Expression\Function\Longest;
+use Yiisoft\Db\Expression\Function\Shortest;
+use Yiisoft\Db\Mysql\Builder\ArrayMergeBuilder;
 use Yiisoft\Db\Mysql\Builder\JsonOverlapsBuilder;
 use Yiisoft\Db\Mysql\Builder\LikeBuilder;
+use Yiisoft\Db\Mysql\Builder\LongestBuilder;
+use Yiisoft\Db\Mysql\Builder\ShortestBuilder;
 use Yiisoft\Db\QueryBuilder\AbstractDQLQueryBuilder;
 use Yiisoft\Db\QueryBuilder\Condition\JsonOverlaps;
 use Yiisoft\Db\QueryBuilder\Condition\Like;
@@ -78,6 +84,9 @@ protected function defaultExpressionBuilders(): array
             JsonOverlaps::class => JsonOverlapsBuilder::class,
             Like::class => LikeBuilder::class,
             NotLike::class => LikeBuilder::class,
+            ArrayMerge::class => ArrayMergeBuilder::class,
+            Longest::class => LongestBuilder::class,
+            Shortest::class => ShortestBuilder::class,
         ];
     }
 }
diff --git a/tests/Provider/QueryBuilderProvider.php b/tests/Provider/QueryBuilderProvider.php
@@ -5,12 +5,18 @@
 namespace Yiisoft\Db\Mysql\Tests\Provider;
 
 use Yiisoft\Db\Constant\ColumnType;
+use Yiisoft\Db\Constant\DataType;
 use Yiisoft\Db\Constant\PseudoType;
+use Yiisoft\Db\Expression\ArrayExpression;
 use Yiisoft\Db\Expression\Expression;
+use Yiisoft\Db\Expression\Function\ArrayMerge;
+use Yiisoft\Db\Expression\Param;
 use Yiisoft\Db\Mysql\Column\ColumnBuilder;
 use Yiisoft\Db\Mysql\Tests\Support\TestTrait;
 
 use function array_replace;
+use function str_contains;
+use function version_compare;
 
 final class QueryBuilderProvider extends \Yiisoft\Db\Tests\Provider\QueryBuilderProvider
 {
@@ -301,4 +307,76 @@ public static function prepareValue(): array
 
         return $values;
     }
+
+    public static function multiOperandFunctionClasses(): array
+    {
+        return [
+            ...parent::multiOperandFunctionClasses(),
+            ArrayMerge::class => [ArrayMerge::class],
+        ];
+    }
+
+    public static function multiOperandFunctionBuilder(): array
+    {
+        $data = parent::multiOperandFunctionBuilder();
+
+        $stringParam = new Param('[3,4,5]', DataType::STRING);
+
+        $data['Longest with 2 operands'][2] = "(SELECT 'short' AS value UNION SELECT :qp0 AS value ORDER BY LENGTH(value) DESC LIMIT 1)";
+        $data['Longest with 3 operands'][2] = "(SELECT 'short' AS value UNION SELECT (SELECT 'longest') AS value UNION SELECT :qp0 AS value ORDER BY LENGTH(value) DESC LIMIT 1)";
+        $data['Shortest with 2 operands'][2] = "(SELECT 'short' AS value UNION SELECT :qp0 AS value ORDER BY LENGTH(value) ASC LIMIT 1)";
+        $data['Shortest with 3 operands'][2] = "(SELECT 'short' AS value UNION SELECT (SELECT 'longest') AS value UNION SELECT :qp0 AS value ORDER BY LENGTH(value) ASC LIMIT 1)";
+
+        $db = self::getDb();
+        $serverVersion = $db->getServerInfo()->getVersion();
+        $db->close();
+
+        $isMariadb = str_contains($serverVersion, 'MariaDB');
+
+        if (
+            $isMariadb && version_compare($serverVersion, '10.6', '<')
+            || !$isMariadb && version_compare($serverVersion, '8.0.0', '<')
+        ) {
+            // MariaDB < 10.6 and MySQL < 8 does not support JSON_TABLE() function.
+            return $data;
+        }
+
+        $data['ArrayMerge with 1 operand'] = [
+            ArrayMerge::class,
+            ["'[1,2,3]'"],
+            "('[1,2,3]')",
+            [1, 2, 3],
+        ];
+        $data['ArrayMerge with 2 operands'] = [
+            ArrayMerge::class,
+            ["'[1,2,3]'", $stringParam],
+            '(SELECT JSON_ARRAYAGG(value) AS value FROM ('
+            . "SELECT value FROM JSON_TABLE('[1,2,3]', '$[*]' COLUMNS(value json PATH '$')) AS t"
+            . " UNION SELECT value FROM JSON_TABLE(:qp0, '$[*]' COLUMNS(value json PATH '$')) AS t) AS t)",
+            [1, 2, 3, 4, 5],
+            [':qp0' => $stringParam],
+        ];
+
+        if ($isMariadb) {
+            // MySQL does not support query parameters in JSON_TABLE() function.
+            $data['ArrayMerge with 4 operands'] = [
+                ArrayMerge::class,
+                ["'[1,2,3]'", [5, 6, 7], $stringParam, self::getDb()->select(new ArrayExpression([9, 10]))],
+                '(SELECT JSON_ARRAYAGG(value) AS value FROM ('
+                . "SELECT value FROM JSON_TABLE('[1,2,3]', '$[*]' COLUMNS(value json PATH '$')) AS t"
+                . " UNION SELECT value FROM JSON_TABLE(:qp0, '$[*]' COLUMNS(value json PATH '$')) AS t"
+                . " UNION SELECT value FROM JSON_TABLE(:qp1, '$[*]' COLUMNS(value json PATH '$')) AS t"
+                . " UNION SELECT value FROM JSON_TABLE((SELECT :qp2), '$[*]' COLUMNS(value json PATH '$')) AS t"
+                . ') AS t)',
+                [1, 2, 3, 4, 5, 6, 7, 9, 10],
+                [
+                    ':qp0' => new Param('[5,6,7]', DataType::STRING),
+                    ':qp1' => $stringParam,
+                    ':qp2' => new Param('[9,10]', DataType::STRING),
+                ],
+            ];
+        }
+
+        return $data;
+    }
 }
diff --git a/tests/QueryBuilderTest.php b/tests/QueryBuilderTest.php
