Improved accessor for arrays with fixed parsing at FQL and added new COMBINE function

Author: lebeda

CHANGELOG.md

@@ -3,7 +3,9 @@
 ## [2.0.1] Unreleased
 
 - Fixed issue with parsing `EXCLUDE` clause 
+- Improved accessor `[]->key` now supports associative arrays by wrapping them into a single-item list, allowing uniform iteration behavior.
 - Replace some string by constant at sql parser
+- Added new function `COMBINE` for combining two arrays
 
 ## [2.0.0]
 

README.md

@@ -7,8 +7,8 @@
 ![Packagist Dependency Version](https://img.shields.io/packagist/dependency-v/1biot/fiquela/php)
 ![Packagist License](https://img.shields.io/packagist/l/1biot/fiquela)
 
-![Static Badge](https://img.shields.io/badge/PHPUnit-tests%3A_171-lightgreen)
-![Static Badge](https://img.shields.io/badge/PHPUnit-asserts%3A_596-lightgreen)
+![Static Badge](https://img.shields.io/badge/PHPUnit-tests%3A_174-lightgreen)
+![Static Badge](https://img.shields.io/badge/PHPUnit-asserts%3A_599-lightgreen)
 ![Static Badge](https://img.shields.io/badge/PHPStan_6-OK-lightgreen)
 ![Static Badge](https://img.shields.io/badge/PHPStan_7|8-16_errors-orange)
 

docs/file-query-language.md

@@ -199,18 +199,20 @@ ORDER BY _score DESC
 
 ### Utils functions
 
-| Function        | Description                                            |
-|-----------------|--------------------------------------------------------|
-| `COALESCE`      | Coalesce values (first non-null value)                 |
-| `COALESCE_NE`   | Coalesce values when not empty (first non-empty value) |
-| `RANDOM_BYTES`  | Generates cryptographically secure random bytes.       |
+| Function       | Description                                            |
+|----------------|--------------------------------------------------------|
+| `COALESCE`     | Coalesce values (first non-null value)                 |
+| `COALESCE_NE`  | Coalesce values when not empty (first non-empty value) |
+| `COMBINE`      | Combine two arrays into a single array                 |
+| `RANDOM_BYTES` | Generates cryptographically secure random bytes.       |
 
 **Examples:**
 
 ```sql
 SELECT
   COALESCE(NULL, 'Hello World') AS coalesce,
   COALESCE_NE(NULL, 'Hello World') AS coalesceNe,
+  COMBINE('filedWitArrayKeys', 'FieldWithArrayValues') AS combined,
   RANDOM_BYTES(16) AS randomBytes
 FROM [jsonFile](./examples/data/products.tmp).data.products
 ```

docs/fluent-api.md

@@ -118,13 +118,15 @@ $query->concat('ArticleNr', 'CatalogNr')->as('CONCAT')
 |--------------------|--------------------------------------------------------|
 | `coalesce`         | Coalesce values (first non-null value)                 |
 | `coalesceNotEmpty` | Coalesce values when not empty (first non-empty value) |
+| `combine`          | Combine two arrays into a single array                 |
 | `randomBytes`      | Generates cryptographically secure random bytes.       |
 
 **Example:**
 
 ```php
 $query->coalesce('whatever', 'ArticleNr')->as('COALESCE')
     ->coalesceNotEmpty('whatever', 'ArticleNr')->as('COALESCE_NE')
+    ->combine('fieldWithArrayKeys', 'fieldWithArrayValues')
     ->randomBytes(16)->as('RANDOM_BYTES');
 ```
 

src/Functions/Utils/Combine.php

@@ -0,0 +1,43 @@
+<?php
+
+namespace FQL\Functions\Utils;
+
+use FQL\Functions;
+use FQL\Traits;
+
+class Combine extends Functions\Core\MultipleFieldsFunction
+{
+    use Traits\Helpers\StringOperations;
+
+    public function __construct(private string $keysArrayField, private string $valueArrayField)
+    {
+        parent::__construct($keysArrayField, $valueArrayField);
+    }
+
+    /**
+     * @inheritDoc
+     * @return array<int|string, mixed>|null
+     */
+    public function __invoke(array $item, array $resultItem): ?array
+    {
+        $keys = $this->getFieldValue($this->keysArrayField, $item, $resultItem);
+        $values = $this->getFieldValue($this->valueArrayField, $item, $resultItem);
+
+        if (
+            !is_array($keys)
+            || !is_array($values)
+        ) {
+            return null;
+        }
+
+        if ($this->isAssoc($keys)) {
+            $keys = array_values($keys);
+        }
+
+        if ($this->isAssoc($values)) {
+            $values = array_values($values);
+        }
+
+        return array_combine($keys, $values);
+    }
+}

src/Interface/Query.php

@@ -448,6 +448,8 @@ public function fulltext(array $fields, string $searchQuery): Query;
     /** @param string[] $fields */
     public function matchAgainst(array $fields, string $searchQuery, ?Fulltext $mode = null): Query;
 
+    public function combine(string $keysArrayField, string $valueArrayField): Query;
+
     /**
      * Specify a specific part of the data to select.
      *

src/Sql/Sql.php

@@ -175,7 +175,7 @@ private function parseFields(Interface\Query $query): void
 
             if (strtoupper($field) === Interface\Query::EXCLUDE) {
                 $mode = 'selectOut';
-                $field = $this->nextToken();
+                continue;
             }
 
             if ($mode === 'selectOut') {
@@ -184,6 +184,12 @@ private function parseFields(Interface\Query $query): void
                 if ($this->isFunction($field)) {
                     $this->applyFunctionToQuery($field, $query);
                 } else {
+                    $nextToken = $this->nextToken();
+                    if (str_starts_with($nextToken, '[]->')) {
+                        $field .= $nextToken;
+                    } else {
+                        $this->rewindToken();
+                    }
                     $query->select($field);
                 }
 
@@ -290,6 +296,7 @@ private function applyFunctionToQuery(string $field, Interface\Query $query): vo
                 )
             ),
             'RANDOM_BYTES' => $query->randomBytes((int) ($arguments[0] ?? 10)),
+            'COMBINE' => $query->combine((string) ($arguments[0] ?? ''), (string) ($arguments[1] ?? '')),
             'MATCH' => $this->processMatchFunction($query, $arguments),
             default => throw new Exception\UnexpectedValueException("Unknown function: $functionName"),
         };

src/Traits/Helpers/NestedArrayAccessor.php

@@ -60,9 +60,10 @@ public function accessNestedValue(array $data, string $field, bool $throwOnMissi
             $subKey = $matches[2];
 
             $nestedArray = $this->accessNestedValue($data, $arrayPath, $throwOnMissing);
-
             if (!is_array($nestedArray)) {
                 throw new InvalidArgumentException(sprintf('Field "%s" is not iterable or does not exist', $arrayPath));
+            } elseif ($this->isAssoc($nestedArray)) {
+                $nestedArray = [$nestedArray];
             }
 
             return array_map(fn($item) => $item[$subKey] ?? null, $nestedArray);
@@ -105,4 +106,13 @@ public function removeNestedValue(array &$data, string $field): void
 
         unset($ref[$lastKey]);
     }
+
+    /**
+     * @param array<int|string, mixed> $array
+     * @return bool
+     */
+    public function isAssoc(array $array): bool
+    {
+        return array_keys($array) !== range(0, count($array) - 1);
+    }
 }

src/Traits/Select.php

@@ -273,6 +273,11 @@ public function matchAgainst(array $fields, string $searchQuery, ?Enum\Fulltext
         return $this->fulltext($fields, $searchQuery);
     }
 
+    public function combine(string $keysArrayField, string $valueArrayField): Interface\Query
+    {
+        return $this->addFieldFunction(new Functions\Utils\Combine($keysArrayField, $valueArrayField));
+    }
+
     private function addFieldFunction(
         Core\BaseFunction|Core\AggregateFunction|Core\NoFieldFunction $function
     ): Interface\Query {

tests/Functions/Utils/CombineTest.php

@@ -0,0 +1,54 @@
+<?php
+
+namespace Functions\Utils;
+
+use FQL\Functions\Utils\Combine;
+use PHPUnit\Framework\TestCase;
+
+class CombineTest extends TestCase
+{
+    public function testCombine(): void
+    {
+        $combine = new Combine('keys', 'values');
+        $this->assertEquals(
+            ['a' => 1, 'b' => 2],
+            $combine(
+                [
+                    'keys' => ['a', 'b'],
+                    'values' => [1, 2],
+                ],
+                []
+            )
+        );
+    }
+
+    public function testCombineWithAssociativeKeys(): void
+    {
+        $combine = new Combine('keys', 'values');
+        $this->assertEquals(
+            ['x' => 1, 'y' => 2],
+            $combine(
+                [
+                    'keys' => ['a' => 'x', 'b' => 'y'],
+                    'values' => [1, 2],
+                ],
+                []
+            )
+        );
+    }
+
+    public function testInvalidKeys(): void
+    {
+        $combine = new Combine('keys', 'values');
+        $this->assertEquals(
+            null,
+            $combine(
+                [
+                    'keys' => 'invalid',
+                    'values' => [1, 2],
+                ],
+                []
+            )
+        );
+    }
+}