Added ArrayLoader with usage example (#1226)

* Added ArrayLoader with usage example

* CS Fixes

examples/topics/data_sink/array/code.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+use function Flow\ETL\DSL\{data_frame, from_array, to_array};
+
+require __DIR__ . '/../../../autoload.php';
+
+$array = [];
+
+data_frame()
+    ->read(from_array([
+        ['id' => 1],
+        ['id' => 2],
+        ['id' => 3],
+        ['id' => 4],
+        ['id' => 5],
+    ]))
+    ->collect()
+    ->write(to_array($array))
+    ->run();
+
+\file_put_contents(__DIR__ . '/output.txt', \var_export($array, true));

examples/topics/data_sink/array/description.md

@@ -0,0 +1,2 @@
+Write datasets directly to an associative array. Please pay attention to the memory usage when using array loader.
+Large datasets may cause memory overflow.  

examples/topics/data_sink/array/output.txt

@@ -0,0 +1,22 @@
+array (
+  0 => 
+  array (
+    'id' => 1,
+  ),
+  1 => 
+  array (
+    'id' => 2,
+  ),
+  2 => 
+  array (
+    'id' => 3,
+  ),
+  3 => 
+  array (
+    'id' => 4,
+  ),
+  4 => 
+  array (
+    'id' => 5,
+  ),
+)

examples/topics/data_sink/array/priority.txt

@@ -0,0 +1 @@
+1

examples/topics/data_sink/parquet/priority.txt

@@ -1 +1 @@
-1
+2

psalm.xml

@@ -35,6 +35,7 @@
     </projectFiles>
     <issueHandlers>
         <RedundantConditionGivenDocblockType errorLevel="suppress" />
+        <ReferenceConstraintViolation errorLevel="suppress" />
         <DocblockTypeContradiction errorLevel="suppress" />
         <RiskyTruthyFalsyComparison errorLevel="suppress" />
         <LessSpecificReturnStatement errorLevel="suppress" />

src/core/etl/src/Flow/ETL/DSL/functions.php

@@ -77,7 +77,7 @@
     When
 };
 use Flow\ETL\Loader\StreamLoader\Output;
-use Flow\ETL\Loader\{CallbackLoader, MemoryLoader, StreamLoader, TransformerLoader};
+use Flow\ETL\Loader\{ArrayLoader, CallbackLoader, MemoryLoader, StreamLoader, TransformerLoader};
 use Flow\ETL\Memory\Memory;
 use Flow\ETL\PHP\Type\Logical\List\ListElement;
 use Flow\ETL\PHP\Type\Logical\Map\{MapKey, MapValue};
@@ -282,6 +282,18 @@ function to_memory(Memory $memory) : MemoryLoader
     return new MemoryLoader($memory);
 }
 
+/**
+ * Convert rows to an array and store them in passed array variable.
+ *
+ * @param-out array<array<mixed>> $array
+ */
+#[DocumentationDSL(module: Module::CORE, type: DSLType::LOADER)]
+#[DocumentationExample(topic: 'data_sink', example: 'array')]
+function to_array(array &$array) : ArrayLoader
+{
+    return new ArrayLoader($array);
+}
+
 #[DocumentationDSL(module: Module::CORE, type: DSLType::LOADER)]
 function to_output(int|bool $truncate = 20, Output $output = Output::rows, Formatter $formatter = new Formatter\AsciiTableFormatter(), SchemaFormatter $schemaFormatter = new ASCIISchemaFormatter()) : StreamLoader
 {

src/core/etl/src/Flow/ETL/Loader/ArrayLoader.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Flow\ETL\Loader;
+
+use Flow\ETL\{FlowContext, Loader, Rows};
+
+final class ArrayLoader implements Loader
+{
+    /**
+     * @param-out array<array<mixed>> $array
+     */
+    public function __construct(private array &$array)
+    {
+    }
+
+    public function load(Rows $rows, FlowContext $context) : void
+    {
+        $this->array = \array_merge(
+            $this->array,
+            $rows->toArray()
+        );
+    }
+}

src/core/etl/tests/Flow/ETL/Tests/Unit/Loader/ArrayLoaderTest.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Flow\ETL\Tests\Unit\Loader;
+
+use function Flow\ETL\DSL\{flow_context, int_entry, row, rows, str_entry, to_array};
+use PHPUnit\Framework\TestCase;
+
+final class ArrayLoaderTest extends TestCase
+{
+    public function test_loads_rows_data_into_memory() : void
+    {
+        $rows1 = rows(
+            row(int_entry('number', 1), str_entry('name', 'one')),
+            row(int_entry('number', 2), str_entry('name', 'two')),
+        );
+
+        $rows2 = rows(
+            row(int_entry('number', 3), str_entry('name', 'three')),
+            row(int_entry('number', 4), str_entry('name', 'four')),
+        );
+
+        $array = [];
+
+        $loader = to_array($array);
+        $loader->load($rows1, flow_context());
+        $loader->load($rows2, flow_context());
+
+        self::assertEquals($rows1->merge($rows2)->toArray(), $array);
+    }
+}