Merge remote-tracking branch 'origin/integration/symfony-isutf8' into…

… integration/symfony-isutf8

.github/workflows/test-suite.yml

@@ -151,7 +151,7 @@ jobs:
         run: "composer install --no-interaction --no-progress --no-suggest"
 
       - name: "Test - ETL "
-        run: "composer test:etl"
+        run: "composer test:core"
 
       - name: "Test - CLI"
         run: "composer test:cli"

CHANGELOG.md

@@ -1,6 +1,9 @@
-## [Unreleased] - 2025-02-10
+## [Unreleased] - 2025-02-11
 
 ### Added
+- [#1465](https://github.com/flow-php/flow/pull/1465) - **jsonl writing example** - [@norberttech](https://github.com/norberttech)
+- [#1465](https://github.com/flow-php/flow/pull/1465) - **csv writing example** - [@norberttech](https://github.com/norberttech)
+- [#1465](https://github.com/flow-php/flow/pull/1465) - **xml writing example** - [@norberttech](https://github.com/norberttech)
 - [f7d9d3](https://github.com/flow-php/flow/commit/f7d9d32c761659668cebc4ded1ebac9706f15e08) - **openssf best practices badge** - [@norberttech](https://github.com/norberttech)
 - [566506](https://github.com/flow-php/flow/commit/5665061429cb78f33b5abbccd27b21e9a38336b3) - **documentation/security page** - [@norberttech](https://github.com/norberttech)
 - [#1455](https://github.com/flow-php/flow/pull/1455) - **DbalMetadata::type - allowing to change the type mapping on a specific column level** - [@norberttech](https://github.com/norberttech)
@@ -81,6 +84,7 @@
 - [#1244](https://github.com/flow-php/flow/pull/1244) - **Added CLI command to read schema from a file** - [@norberttech](https://github.com/norberttech)
 
 ### Changed
+- [#1465](https://github.com/flow-php/flow/pull/1465) - **Improved contributing md** - [@norberttech](https://github.com/norberttech)
 - [#1462](https://github.com/flow-php/flow/pull/1462) - **Improve error message when schema definition is duplicated** - [@norberttech](https://github.com/norberttech)
 - [#1453](https://github.com/flow-php/flow/pull/1453) - **Change StringCamel to StringStyle to using with exisitng Enum StringStyles and get's StringStyle as parameter** - [@f-lapinski](https://github.com/f-lapinski)
 - [#1456](https://github.com/flow-php/flow/pull/1456) - **Count aggregating function does not require reference anymore** - [@norberttech](https://github.com/norberttech)

composer.json

@@ -217,7 +217,7 @@
             "@test:mutation"
         ],
         "test": [
-            "@test:etl",
+            "@test:core",
             "@test:cli",
             "@test:lib:array-dot",
             "@test:lib:azure-sdk",
@@ -244,7 +244,7 @@
             "@test:adapter:text",
             "@test:adapter:xml"
         ],
-        "test:etl": [
+        "test:core": [
             "tools/phpunit/vendor/bin/phpunit --testsuite=etl-unit --log-junit ./var/phpunit/logs/etl-unit.junit.xml --coverage-clover=./var/phpunit/coverage/clover/etl-unit.coverage.xml --coverage-html=./var/phpunit/coverage/html/etl-unit",
             "tools/phpunit/vendor/bin/phpunit --testsuite=etl-integration --log-junit ./var/phpunit/logs/etl-integration.junit.xml --coverage-clover=./var/phpunit/coverage/clover/etl-integration.coverage.xml --coverage-html=./var/phpunit/coverage/html/etl-integration"
         ],

documentation/contributing.md

@@ -1,53 +1,92 @@
 # Contributing
 
-In order to run tests locally please make sure you have [docker](https://www.docker.com/) up and running.
-You also need [PHP 8.1](https://www.php.net/) and [composer](https://getcomposer.org/) to be available from your CLI.
-Even that we are supporting 3 PHP versions at time, we are using the lowest supported one for development, currently it's PHP 8.1.
+To run tests locally, please make sure you have [docker](https://www.docker.com/) up and running.
+You also need [PHP 8.2](https://www.php.net/) and [composer](https://getcomposer.org/) to be available from your CLI.
+Even though we are supporting 3 PHP versions at the time, we are using the lowest supported one for development, currently it's PHP 8.2.
 
-For the code coverage, please install [pcov](https://pecl.php.net/package/pcov).
 
-### Before you change anything
+## Before you change anything
 
 Please make sure that you are aware of our [Architecture Decision Records](/documentation/adrs.md).
 It's mandatory to follow all of them without any exceptions unless explicitly overridden by a new ADR.
 
-### Prepare Project:
+## Prepare Project:
 
 ```shell
 cp compose.yml.dist compose.yml
 composer install 
 docker compose up -d
 ```
 
-### Run Test Suite
+For the code coverage, please install [pcov](https://pecl.php.net/package/pcov).
+
+Pcov extension is not mandatory, and tests are going to pass without it; however, you won't be able to run mutation tests. 
+
+## Run Test Suite
 
 ```shell
 composer test
 ```
 
-### Run Static Analyze
+Above command will run all tests, including those that require custom extensions.
+In case you want to run tests only for a specific part of the project, you can use: 
+
+
+```shell
+composer test:core
+composer test:lib:doctrine-dbal-bulk
+composer test:lib:parquet
+composer test:adapter:csv
+composer test:bridge:symfony-http-foundation
+```
+
+## Run Static Analyze
 
 ```shell
 composer static:analyze
 ```
 
-### Fixing Coding Standards
+**Important** static analyze **MUST** be executed at the lowest supported PHP version
+and with dependencies locked by `composer.lock`. 
+Please make sure to use PHP 8.2 and that you used the `composer install` command first.
+
+## Fixing Coding Standards
 
 Before committing your code, please make sure that your code is following our coding standards.
 
 ```shell
 composer cs:php:fix
 ```
 
-### Test everything
+This command will automatically fix all coding standards issues in your code.
+If you want to first check what needs to be fixed, you can use:
 
-This command will execute exactly the same tests as we run at GitHub Actions before PR can get merged.
-If it passes locally, you are good to open pull request.
+
+```shell
+composer static:analyze:cs-fixer
+composer static:analyze:rector
+```
+
+## Test everything
+
+This command will execute exactly the same tests as we run at GitHub Actions before a PR can get merged.
+If it passes locally, you are good to open a pull request.
 
 ```shell
 composer build 
 ```
 
+## Building Documentation
+
+Since documentation for DSL and our entire API is automatically generated, you can build it by running:
+
+```shell
+composer build:docs
+composer build:docs:api
+```
+
+`composer build:docs` must be executed after any adjustments to `functions.php` files (DSL).
+
 ## Building PHAR
 
 ```shell
@@ -60,7 +99,7 @@ composer build:phar
 In order to build docker image and load it to local registry please use: 
 
 ```shell
-docker buildx build -t flow-php/flow:latest . --progress=plain  --load
+docker buildx build -t flow-php/flow:latest . --progress=plain --load
 ```
 
 Usage:

examples/run.php

@@ -25,18 +25,34 @@
 
 \ini_set('memory_limit', -1);
 
-$finder = new Finder();
-$finder->in(__DIR__ . '/topics')
-    ->files()
-    ->name('*.php');
-
 $output = new ConsoleOutput();
 $intput = new ArgvInput(definition: new InputDefinition(
     [
         new InputOption(name: 'composer-update', shortcut: 'u', mode: InputOption::VALUE_NONE),
         new InputOption(name: 'composer-archive', shortcut: 'a', mode: InputOption::VALUE_NONE),
+        new InputOption(name: 'topic', shortcut: 't', mode: InputOption::VALUE_REQUIRED),
+        new InputOption(name: 'example', shortcut: 'e', mode: InputOption::VALUE_REQUIRED),
     ]
 ));
+
+$topic = $intput->getOption('topic');
+$example = $intput->getOption('example');
+
+$path = __DIR__ . '/topics';
+
+if ($topic) {
+    $path .= '/' . $topic;
+}
+
+if ($example) {
+    $path .= '/' . $example;
+}
+
+$finder = new Finder();
+$finder->in($path)
+    ->files()
+    ->name('*.php');
+
 $style = new SymfonyStyle($intput, $output);
 $style->setDecorated(true);
 

examples/topics/data_writing/csv/code.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+use function Flow\ETL\Adapter\CSV\to_csv;
+use function Flow\ETL\DSL\{data_frame, from_array, overwrite};
+
+require __DIR__ . '/vendor/autoload.php';
+
+data_frame()
+    ->read(
+        from_array([
+            ['id' => 1, 'name' => 'John', 'age' => 30],
+            ['id' => 2, 'name' => 'Jane', 'age' => 25],
+            ['id' => 3, 'name' => 'Bob', 'age' => 35],
+            ['id' => 4, 'name' => 'Alice', 'age' => 28],
+            ['id' => 5, 'name' => 'Charlie', 'age' => 32],
+        ])
+    )
+    ->collect()
+    ->mode(overwrite())
+    ->write(to_csv(__DIR__ . '/output.csv'))
+    ->run();

examples/topics/data_writing/csv/composer.json

@@ -0,0 +1,16 @@
+{
+  "name": "flow-php/examples",
+  "description": "Flow PHP - Examples",
+  "license": "MIT",
+  "type": "library",
+  "require": {
+    "flow-php/etl": "1.x-dev",
+    "flow-php/etl-adapter-csv": "1.x-dev"
+  },
+  "archive": {
+    "exclude": [
+      ".env",
+      "vendor"
+    ]
+  }
+}