Added new array_merge and format_date functions, renamed combine function to array_combine and recognizing datetime in result and create DateTimeImmutable object

Author: lebeda

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [2.0.2]
+
+- Rename `COMBINE` to `ARRAY_COMBINE`
+- Added new function `ARRAY_MERGE` for merging two arrays
+- Automatically recognize date from selected string and cast it to `\DateTimeImmutable`
+- When `\DateTimeImmutable` casting to the string, it will be formatted to `c` format (`Y-m-d\TH:i:sP`)
+- Added new function `DATE_FORMAT` for formatting `\DateTimeImmutable` to string
+
 ## [2.0.1]
 
 - Fixed issue with parsing `EXCLUDE` clause 

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_174-lightgreen)
-![Static Badge](https://img.shields.io/badge/PHPUnit-asserts%3A_599-lightgreen)
+![Static Badge](https://img.shields.io/badge/PHPUnit-tests%3A_180-lightgreen)
+![Static Badge](https://img.shields.io/badge/PHPUnit-asserts%3A_605-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)
 
@@ -22,7 +22,7 @@ various sources, **F**i**Q**ue**L**a provides a seamless way to manipulate and e
 - 📂 **Supports multiple formats**: Work seamlessly with XML, CSV, JSON, NDJSON, YAML, and NEON.
 - 🛠️ **SQL-inspired syntax**: Perform `SELECT`, `JOIN`, `WHERE`, `GROUP BY`, `ORDER BY` and more.
 - ✍️ **Flexible Querying**: Write SQL-like strings or use the fluent API for maximum flexibility.
-- 📊 **Advanced functions**: Access features like `SUM`, `COUNT`, `AVG`, `GROUP_CONCAT`, `COMBINE`, `MD5` and many more.
+- 📊 **Advanced functions**: Access features like `SUM`, `COUNT`, `GROUP_CONCAT`, `ARRAY_MERGE`, `FORMAT_DATE` and many more.
 - 🚀 **Efficient with Large Files**: Optimized for processing JSON, XML, and CSV files with tens of thousands of rows using stream processing.
 - 🧑‍💻 **Developer-Friendly**: Map results to DTOs for easier data manipulation.
 - ⭐ **Unified API across all supported formats**: Use a consistent API for all your data needs.
@@ -295,7 +295,8 @@ to load all data into memory. It may cause memory issues for large datasets. But
 ## 8. Planning Features
 
 - [ ] **Operator BETWEEN**: Add operator `BETWEEN` for filtering data and add support for dates and ranges.
-- [ ] **Next file formats**: Add next file formats [MessagePack](https://msgpack.org/), [INI](https://en.wikipedia.org/wiki/INI_file), [XLSX](https://en.wikipedia.org/wiki/Excel_Open_XML_file_formats) and [TOML](https://toml.io/en/)
+- [ ] **Next file formats**: Add next file formats [MessagePack](https://msgpack.org/), [XLSX](https://en.wikipedia.org/wiki/Excel_Open_XML_file_formats), [INI](https://en.wikipedia.org/wiki/INI_file) and [TOML](https://toml.io/en/)
+- [ ] **Custom cast type**: Add support for custom cast type for `SELECT` clause.
 - [ ] **Documentation**: Create detailed guides and examples for advanced use cases.
 - [ ] **Add explain method**: Add method `explain()` for explaining query execution from actual query debugger and provide more complex information about query.
 - [ ] **PHPStan 8**: Fix all PHPStan 8 errors.

docs/file-query-language.md

@@ -199,21 +199,25 @@ 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) |
-| `COMBINE`      | Combine two arrays into a single array                 |
-| `RANDOM_BYTES` | Generates cryptographically secure random bytes.       |
+| Function        | Description                                                           |
+|-----------------|-----------------------------------------------------------------------|
+| `ARRAY_COMBINE` | Combine two array with keys and array with values into a single array |
+| `ARRAY_MERGE`   | Merge two arrays into a single array                                  |
+| `COALESCE`      | Coalesce values (first non-null value)                                |
+| `COALESCE_NE`   | Coalesce values when not empty (first non-empty value)                |
+| `FORMAT_DATE`   | Format date field to string                                           |
+| `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
+    ARRAY_COMBINE(filedWitArrayKeys, FieldWithArrayValues) AS arrayCombine,
+    ARRAY_MERGE(fieldWithArray1, fieldWithArray2) AS arrayMerge,
+    COALESCE(NULL, 'Hello World') AS coalesce,
+    COALESCE_NE(NULL, 'Hello World') AS coalesceNe,
+    FORMAT_DATE(dateField, 'Y-m-d') AS dateFormat,
+    RANDOM_BYTES(16) AS randomBytes
 FROM [jsonFile](./examples/data/products.tmp).data.products
 ```
 

docs/fluent-api.md

@@ -114,19 +114,23 @@ $query->concat('ArticleNr', 'CatalogNr')->as('CONCAT')
 
 ### Utils functions
 
-| Function           | Description                                            |
-|--------------------|--------------------------------------------------------|
-| `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.       |
+| Function           | Description                                                            |
+|--------------------|------------------------------------------------------------------------|
+| `arrayCombine`     | Combine two array with keys and array with values into a single array  |
+| `arrayMerge`       | Merge two arrays into a single array                                   |
+| `coalesce`         | Coalesce values (first non-null value)                                 |
+| `coalesceNotEmpty` | Coalesce values when not empty (first non-empty value)                 |
+| `formatDate`       | Format date field to string                                            |
+| `randomBytes`      | Generates cryptographically secure random bytes.                       |
 
 **Example:**
 
 ```php
-$query->coalesce('whatever', 'ArticleNr')->as('COALESCE')
+$query->arrayCombine('fieldWithArrayKeys', 'fieldWithArrayValues')->as('ARRAY_COMBINE')
+    ->arrayMerge('fieldWithArray1', 'fieldWithArray2')->as('ARRAY_MERGE')
+    ->coalesce('whatever', 'ArticleNr')->as('COALESCE')
     ->coalesceNotEmpty('whatever', 'ArticleNr')->as('COALESCE_NE')
-    ->combine('fieldWithArrayKeys', 'fieldWithArrayValues')
+    ->formatDate('dateField', 'Y-m-d')->as('FORMAT_DATE')
     ->randomBytes(16)->as('RANDOM_BYTES');
 ```
 

examples/data/products.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <root>
-    <item id="1" category="A">
+    <item id="1" category="A" created="2025-04-08T12:29:38Z">
         <name>Item 1</name>
         <price>100</price>
         <brand>
@@ -16,7 +16,7 @@
             <gallery_image>http://example.com/g/1.jpg</gallery_image>
         </gallery>
     </item>
-    <item id="2" category="B">
+    <item id="2" category="B" created="2025-04-03T11:43:21+02:00">
         <name>Item 2</name>
         <price>200</price>
         <brand>

src/Enum/Type.php

@@ -20,6 +20,8 @@ enum Type: string
     case ARRAY = 'array';
     case OBJECT = 'object';
 
+    case DATETIME = 'datetime';
+
     case RESOURCE = 'resource';
     case RESOURCE_CLOSED = 'resource (closed)';
 
@@ -34,6 +36,10 @@ public static function castValue(mixed $value, ?Type $type = null): mixed
             self::FLOAT => is_numeric($value) ? (float) $value : 0.0,
             self::BOOLEAN => (bool) filter_var($value, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE),
             self::NULL => null,
+            self::DATETIME => match (true) {
+                $value instanceof \DateTimeInterface => $value,
+                default => \DateTimeImmutable::createFromFormat(DATE_ATOM, self::toString($value)),
+            },
             self::ARRAY => is_array($value) ? $value : [$value],
             self::OBJECT => is_object($value) ? $value : null,
             default => throw new InvalidArgumentException(
@@ -50,7 +56,10 @@ public static function match(mixed $value): self
             'double' => self::FLOAT,
             'string' => self::STRING,
             'array' => self::ARRAY,
-            'object' => self::OBJECT,
+            'object' => match (true) {
+                $value instanceof \DateTimeInterface => self::DATETIME,
+                default => self::OBJECT,
+            },
             'resource' => self::RESOURCE,
             'resource (closed)' => self::RESOURCE_CLOSED,
             'NULL' => self::NULL,
@@ -70,6 +79,16 @@ public static function matchByString(string $value): mixed
             return self::castValue(strtolower($value) === 'true' ? 1 : 0, self::BOOLEAN);
         }
 
+        // Datetime / Timestamp
+        if (preg_match('/^\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})?$/', $value)) {
+            try {
+                return self::castValue(new \DateTimeImmutable(self::toString($value)));
+            } catch (\Exception) {
+                // Invalid date format
+                return self::castValue($value, self::STRING);
+            }
+        }
+
         // Integer or Float
         if (self::isNumeric($value)) {
             $type = self::INTEGER;
@@ -124,13 +143,19 @@ private static function isNumeric(string $value): bool
     private static function toString(mixed $value): string
     {
         $type = self::match($value);
-        return match ($type) {
-            self::NULL => 'null',
-            self::TRUE => 'true',
-            self::FALSE => 'false',
-            self::ARRAY => 'array',
-            self::OBJECT => 'object',
-            default => (string) $value,
-        };
+        try {
+            return match ($type) {
+                self::NULL => 'null',
+                self::TRUE => 'true',
+                self::FALSE => 'false',
+                self::ARRAY => json_encode($value),
+                self::DATETIME => $value instanceof \DateTimeInterface ? $value->format('c') : 'null',
+                self::OBJECT => $value instanceof \Serializable ? $value->serialize() : 'object',
+                self::STRING => $value,
+                default => (string) $value,
+            };
+        } catch (\Exception) {
+            return 'null';
+        }
     }
 }

src/Functions/Utils/Combine.php src/Functions/Utils/ArrayCombine.phpsrc/Functions/Utils/Combine.php renamed to src/Functions/Utils/ArrayCombine.php

@@ -5,7 +5,7 @@
 use FQL\Functions;
 use FQL\Traits;
 
-class Combine extends Functions\Core\MultipleFieldsFunction
+class ArrayCombine extends Functions\Core\MultipleFieldsFunction
 {
     use Traits\Helpers\StringOperations;
 

src/Functions/Utils/ArrayMerge.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace FQL\Functions\Utils;
+
+use FQL\Functions;
+use FQL\Traits;
+
+class ArrayMerge 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;
+        }
+
+        return array_merge($keys, $values);
+    }
+}

src/Functions/Utils/DateFormat.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace FQL\Functions\Utils;
+
+use FQL\Functions;
+
+class DateFormat extends Functions\Core\MultipleFieldsFunction
+{
+    public function __construct(private readonly string $field, private readonly string $format = 'c')
+    {
+        parent::__construct($field, $format);
+    }
+
+    public function __invoke(array $item, array $resultItem): ?string
+    {
+        $value = $this->getFieldValue($this->field, $item, $resultItem) ?? $this->field;
+        if (!$value instanceof \DateTimeImmutable) {
+            return null;
+        }
+
+        return $value->format($this->format);
+    }
+
+    public function __toString(): string
+    {
+        return sprintf(
+            '%s(%s, "%s")',
+            $this->getName(),
+            $this->field,
+            $this->format
+        );
+    }
+}

src/Interface/Query.php

@@ -448,7 +448,9 @@ 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;
+    public function arrayCombine(string $keysArrayField, string $valueArrayField): Query;
+    public function arrayMerge(string $keysArrayField, string $valueArrayField): Query;
+    public function formatDate(string $dateField, string $format = 'c'): Query;
 
     /**
      * Specify a specific part of the data to select.