Merge branch 'main' into 208

Author: njoubert-cleverage

.github/ISSUE_TEMPLATE/bug.md

@@ -0,0 +1,58 @@
+---
+name: Bug report
+about: Report a task, transformer or engine behaving incorrectly
+title: ''
+labels: bug
+assignees: ''
+---
+
+## Description
+
+<!-- What is wrong, in one or two sentences. List each symptom when there are several (wrong output, exception, silent failure...) -->
+
+### Reproduction
+
+<!-- A minimal process configuration reproducing the bug, ideally a demo.* process from https://github.com/cleverage/process-bundle-demo -->
+
+```yaml
+clever_age_process:
+    configurations:
+        demo.<name>:
+            tasks:
+                <task>:
+                    service: '@CleverAge\ProcessBundle\Task\...'
+                    options: {}
+                    outputs: [debug]
+                debug:
+                    service: '@CleverAge\ProcessBundle\Task\Debug\DebugTask'
+```
+
+<!-- Input data, command and actual output -->
+
+```
+$ bin/console cleverage:process:execute demo.<name>
+```
+
+Expected: `<expected output>`
+
+Tested on `main` (`<commit>`), PHP x.y, Symfony x.y.
+
+### Cause
+
+<!-- Optional: where the bug comes from, with links to the relevant lines -->
+
+### Proposed fix
+
+<!-- Optional: how to fix it, and which documentation must be updated -->
+
+## Requirements
+
+* Documentation updates
+  - [ ] Reference
+  - [ ] Cookbooks
+  - [ ] Changelog
+* [ ] Unit tests
+
+## Breaking changes
+
+<!-- Behaviour changes introduced by the fix, or "None" with the reason (e.g. every configuration of this task currently fails) -->

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

.github/ISSUE_TEMPLATE.md .github/ISSUE_TEMPLATE/issue.md.github/ISSUE_TEMPLATE.md renamed to .github/ISSUE_TEMPLATE/issue.md

@@ -1,3 +1,11 @@
+---
+name: Feature request / other
+about: Propose an enhancement, a refactoring or any other change
+title: ''
+labels: ''
+assignees: ''
+---
+
 ## Description
 
 <!-- Please describe the issue here -->

CHANGELOG.md

@@ -9,6 +9,15 @@ Latest
 * [#192](https://github.com/cleverage/process-bundle/issues/192) Fix CommandRunnerTask: only pass the `options` option to `Process::setOptions()`, support string `commandline` through `Process::fromShellCommandline()`, validate option types. Update documentation, add tests.
 * [#194](https://github.com/cleverage/process-bundle/issues/194) Fix ProcessLauncherTask: the `process_options` normalizer returned an array despite its scalar return type, so the task always failed with a `TypeError`. Update documentation, add tests.
 * [#189](https://github.com/cleverage/process-bundle/issues/189) Fix EventDispatcherTask: dispatch the event under the `event_name` option (regression since v4.0). `event_name` is now optional: when `null` (default), the event is dispatched under its class name. Update documentation, add tests.
+* [#198](https://github.com/cleverage/process-bundle/issues/198) Fix DateParserTransformer: a `\DateTimeImmutable` input is converted to a `\DateTime` instead of throwing a `TypeError`. Update documentation, add tests.
+* [#199](https://github.com/cleverage/process-bundle/issues/199) Fix PregFilterTransformer: an array `replacement` is no longer cast to the string `"Array"`, and requires an array `pattern`. Update documentation, add tests.
+* [#200](https://github.com/cleverage/process-bundle/issues/200) Fix GenericTransformer: a contextual option declared with `required: false` and no default can now be used; its placeholders are replaced by `null` when omitted. Update documentation, add tests.
+* [#202](https://github.com/cleverage/process-bundle/issues/202) Fix XmlReaderTask: throw an explicit `\UnexpectedValueException` on an empty file or invalid XML (with the libxml error messages) instead of a `ValueError` or a silent empty `\DOMDocument`. Update documentation, add tests.
+* [#203](https://github.com/cleverage/process-bundle/issues/203) Fix `ProcessState::addErrorContextValue()`: accept any value type, so that iterable tasks on an empty iterable are skipped and PropertySetterTask reports the original exception instead of a `TypeError`. Update documentation, add tests.
+* [#204](https://github.com/cleverage/process-bundle/issues/204) Fix CachedTransformer, SlugifyTransformer and TypeSetterTransformer edge cases: accept a non-string input in `cached` (key built after `key_transformers`), reject an invalid `transliterator` in `slugify` with an `InvalidOptionsException`, remove the unreachable error branch of `type_setter`. Update documentation, add tests.
+* [#205](https://github.com/cleverage/process-bundle/issues/205) Fix FileSplitterTask: produced files lost the first line, doubled line breaks and ended with an empty file; each file now contains exactly `max_lines` lines of the source. Update documentation, add tests.
+* [#206](https://github.com/cleverage/process-bundle/issues/206) Fix AdvancedStatCounterTask, IterableBatchTask, ConditionTrait and ColumnAggregatorTask edge cases: log the first counted execution with correct counts, accept a `null` `batch_count` (only flush at the end), allow scalar inputs in conditions (`''` path on the whole value), aggregate `null` column values. Update documentation, add tests.
+* [#207](https://github.com/cleverage/process-bundle/issues/207) Fix JsonStreamReaderTask / JsonStreamWriterTask: throw an explicit `\UnexpectedValueException` when a line decodes to a scalar, create the missing parent directory when writing. Update documentation, add tests.
 * [#208](https://github.com/cleverage/process-bundle/issues/208) Fix FolderBrowserTask, InputFolderBrowserTask, CsvReaderTask and LineReaderTask (and their `Input*` variants): reset the state at the end of the iteration, so that a following input is read from its beginning. Update documentation, add tests.
 
 ## Deprecated

docs/03-custom_tasks.md

@@ -82,8 +82,8 @@ Sometimes, when you execute a task, you need to change how the process continues
   `error_strategy` is then applied (throwing an exception from `execute` has the same effect)
 * `ProcessState::setErrorOutput($value)`: send a value to the error branch of your workflow (the tasks listed in
   `error_outputs`)
-* `ProcessState::addErrorContextValue($key, $value)` / `removeErrorContext($key)`: add information to the log record
-  written when an error occurs
+* `ProcessState::addErrorContextValue($key, $value)` / `removeErrorContext($key)`: add information (any value) to the
+  log record written when an error occurs
 
 ## Options
 

docs/reference/03-generic_transformers_definition.md

@@ -33,7 +33,8 @@ For each contextual option, you can define
 | `default_is_null` | `bool` | | `false` | If you need `null` to be the default value, use this option |
 
 Note that an option with a default value is still required by default, which has no effect since the default is used:
-set `required: false` for an option without default value that may be omitted.
+set `required: false` for an option without default value that may be omitted: when omitted, its placeholders are
+replaced by `null`.
 
 The `transformers` list uses the same syntax as any other transformer using a sub-list of transformers (see
 [TransformerTrait](traits/transformer_trait.md)).

docs/reference/tasks/advanced_stat_counter_task.md

@@ -17,7 +17,7 @@ Input is ignored, only the number of executions matters.
 Possible outputs
 ----------------
 
-`null` when statistics are logged, otherwise the task is skipped (nothing is sent to the outputs). It is meant to be
+`null` when statistics are logged (with `show_every: 1`, on every counted execution), otherwise the task is skipped (nothing is sent to the outputs). It is meant to be
 used as the last task of a branch.
 
 The logged message has the following format:
@@ -33,7 +33,7 @@ Options
 |--------------|-------|:--------:|---------|---------------------------------------------------------------------------------------|
 | `num_items`  | `int` |          | `1`     | Number of items represented by one execution (multiplier of the counter)              |
 | `skip_first` | `int` |          | `0`     | Number of first executions to ignore (the elapsed time still starts at the first one) |
-| `show_every` | `int` |          | `1`     | Log the statistics every N executions (the first counted execution is never logged)   |
+| `show_every` | `int` |          | `1`     | Log the statistics every N counted executions (the N-th, 2N-th, ...)                  |
 
 Examples
 --------

docs/reference/tasks/column_aggregator_task.md

@@ -13,8 +13,8 @@ Task reference
 Accepted inputs
 ---------------
 
-`array`: an associative array that should contain the configured `columns` (a column whose value is `null` is
-considered missing)
+`array`: an associative array that should contain the configured `columns` (a column is present as soon as its key
+exists, even if its value is `null`)
 
 Possible outputs
 ----------------

docs/reference/tasks/file_splitter_task.md

@@ -19,8 +19,8 @@ file path as input. Any other input is ignored.
 Possible outputs
 ----------------
 
-`string`: path of a temporary file (created in the system temporary directory, with a `.tmp` extension) containing a
-chunk of lines of the source file.
+`string`: path of a temporary file (created in the system temporary directory, with a `.tmp` extension) containing the
+next `max_lines` lines of the source file (the last file may contain fewer lines).
 
 Options
 -------
@@ -49,5 +49,8 @@ Notes
 -----
 
 * Values given as input are merged after option resolution, so they are not validated.
+* Every line of the source file is kept, in order, including empty lines. Line content is preserved, but each line
+  break (`\n` or `\r\n`) is written as `PHP_EOL`, and a missing line break on the last line is added.
+* An empty source file produces no output (the task is skipped).
 * Temporary files are not deleted by the task, use [FileRemoverTask](file_remover_task.md) if needed.
 * For CSV files, prefer [CsvSplitterTask](csv_splitter_task.md) which keeps the headers in each produced file.

docs/reference/tasks/filter_task.md

@@ -12,7 +12,8 @@ Task reference
 Accepted inputs
 ---------------
 
-`array` or `object`: values are read with the Symfony PropertyAccessor. A non-readable property is considered `null`.
+`any`: on an `array` or an `object`, values are read with the Symfony PropertyAccessor; a non-readable property is
+considered `null`. On a scalar input, use the empty path `''` to test the whole value (any other path gives `null`).
 
 Possible outputs
 ----------------