Merge branch 'main' into 244

Author: njoubert-cleverage

CHANGELOG.md

@@ -4,9 +4,16 @@ Latest
 ## Changes
 * [#197](https://github.com/cleverage/process-bundle/issues/197) Add missing tests: every Task and Transformer is now covered by unit tests. Remove the obsolete `tests.old` directory.
 * [#143](https://github.com/cleverage/process-bundle/issues/143) Improve PHPStan configuration: remove all `ignoreErrors` and `@phpstan-ignore` comments (report unmatched ignored errors again), add missing iterable value types and generic types in PHPDoc, remove unreachable code in AbstractIterableOutputTask and InputAggregatorTask.
+* [#143](https://github.com/cleverage/process-bundle/issues/143) Improve PHPStan level from 6 to 7, and fix the level 8 errors that do not require a signature change (the remaining ones, due to nullable return types such as `AbstractConfigurableTask::getOptions(): ?array`, will be fixed in v6.0). Default to a `ContextualOptionResolver` in ProcessState and to a property accessor in ConditionTrait when none is set.
 
 ## Fixes
 * [#143](https://github.com/cleverage/process-bundle/issues/143) Fix InputIteratorTask: an `\IteratorAggregate` input whose `getIterator()` does not return an `\Iterator` (e.g. another `\IteratorAggregate`) is iterated instead of failing with a `TypeError`. Update documentation, add tests.
+* [#143](https://github.com/cleverage/process-bundle/issues/143) Fix level 8 edge cases failing with a `TypeError` or an `Error`: `CsvResource` rejects a blank header line and checks `ftell()`, XpathEvaluatorTransformer throws an explicit `\UnexpectedValueException` on an invalid query (with the libxml messages), a namespace node to unwrap or a node without document, SlugifyTransformer on a value that cannot be transliterated, `ProcessState::getContext()` returns `[]` until the context is defined, GenericTransformer and TransformerTrait throw a `\LogicException` when not initialized, IterableBatchTask and JsonStreamReaderTask can be flushed / iterated before their first execution, RegistryCompilerPass checks its configuration, SubprocessInstance checks the PHP executable. Update documentation, add tests.
+* [#239](https://github.com/cleverage/process-bundle/issues/239) Fix PropertyGetterTask: catch any `\Throwable`, so that the `TypeError` of the property accessor on a scalar input is set on the state (with the `property` error context) and handled according to the task `error_strategy` instead of escaping it. Update documentation, add tests.
+* [#241](https://github.com/cleverage/process-bundle/issues/241) Fix CsvWriterTask: a non-array input throws the documented `\UnexpectedValueException` instead of a `TypeError` when `headers` is `null`, and the CSV tasks release their file on `finalize()` so that the task can be executed again. Update documentation, add tests.
+* [#240](https://github.com/cleverage/process-bundle/issues/240) Fix FileMoverTask: with `autoincrement`, the suffix was computed on the whole path (a dot in a directory name was taken as the extension, making the move fail for a file without extension) and an existing numeric suffix of the file name was replaced (`report-2024.csv` became `report-1.csv`). The suffix is now appended to the file name only (`report-2024-1.csv`, `file-1`, `.env-1`). Update documentation, add tests.
+* [#243](https://github.com/cleverage/process-bundle/issues/243) Fix RecursivePropertySetterTransformer: a `\stdClass` item without the property was replaced by a copy in the output, so the input object was not modified; the property is now added to the item itself. Update documentation, add tests.
+* [#242](https://github.com/cleverage/process-bundle/issues/242) Fix InputFileReaderTask: an input that is not a non-empty string (e.g. `null`) throws an explicit `\UnexpectedValueException` (`No file path given as input`) instead of a PHP warning followed by a `TypeError`. Update documentation, add tests.
 * [#244](https://github.com/cleverage/process-bundle/issues/244) Fix MappingTransformer: a missing target property of a `\stdClass` destination (`initial_value` or `keep_input`) threw `Property '...' is not writable`, it is now added when the target is a simple property name (nested paths still throw). Update documentation, add tests.
 
 v5.1

docs/reference/tasks/csv_reader_task.md

@@ -70,7 +70,8 @@ Notes
 -----
 
 * Each line must contain exactly as many columns as there are headers, otherwise an `\UnexpectedValueException` is thrown.
-* A UTF-8 BOM is removed from the first header when headers are read from the file.
+* A UTF-8 BOM is removed from the first header when headers are read from the file. If the first line is blank, an
+  `\UnexpectedValueException` is thrown.
 * `csv_file` and `csv_line` are added to the error context of the process.
 * The file is closed once fully read: if the task is executed again (e.g. for a new input), the file is read again
   from its beginning.

docs/reference/tasks/csv_writer_task.md

@@ -76,5 +76,6 @@ Notes
 * `{date}` is replaced by `Ymd`, `{date_time}` by `Ymd_His`, `{timestamp}` by the Unix timestamp and `{unique_token}`
   by a `uniqid()` value.
 * The parent directory of the file is created if needed.
+* An input that is not an `array` throws an `\UnexpectedValueException`.
 * Each input must contain every header key (extra keys are not allowed: the number of columns must match the number of
   headers), otherwise an `\UnexpectedValueException` is thrown. Columns are written in the headers order.

docs/reference/tasks/file_mover_task.md

@@ -26,7 +26,7 @@ Options
 |-----------------|----------|:--------:|---------|--------------------------------------------------------------------------------------------------------------------------|
 | `destination`   | `string` |  **X**   |         | Destination path. If it is an existing directory, the original file name is kept                                         |
 | `overwrite`     | `bool`   |          | `false` | Allow overwriting an existing file at destination (otherwise an exception is thrown)                                     |
-| `autoincrement` | `bool`   |          | `false` | If the destination file exists, add or increment a numeric suffix before the extension (e.g. `file-1.csv`, `file-2.csv`) |
+| `autoincrement` | `bool`   |          | `false` | If the destination file exists, append the first free numeric suffix to the file name, before its extension (e.g. `file-1.csv`, `file-2.csv`) |
 
 Examples
 --------
@@ -46,3 +46,6 @@ Notes
 -----
 
 * Underlying method is Symfony `Filesystem::rename()`.
+* With `autoincrement`, only the file name is changed (never the directory part), and the suffix is always appended to
+  the original name: `report-2024.csv` becomes `report-2024-1.csv`, `file` becomes `file-1`, `archive.tar.gz` becomes
+  `archive.tar-1.gz` and a hidden file `.env` becomes `.env-1`.

docs/reference/tasks/input_file_reader_task.md

@@ -12,8 +12,8 @@ Task reference
 Accepted inputs
 ---------------
 
-`string`: path of the file to read. An `\UnexpectedValueException` is thrown if the file does not exist or is not
-readable.
+`string`: path of the file to read. An `\UnexpectedValueException` is thrown if the input is not a non-empty string
+(e.g. `null`, `''`), or if the file does not exist or is not readable.
 
 Possible outputs
 ----------------

docs/reference/tasks/property_getter_task.md

@@ -21,8 +21,8 @@ Possible outputs
 
 `mixed`: the value read at the `property` path.
 
-If the value cannot be read, the exception is set on the state (with the `property` added to the error context) and
-handled according to the task `error_strategy`.
+If the value cannot be read (including a `\TypeError` of the property accessor, e.g. on a scalar input), the exception
+is set on the state (with the `property` added to the error context) and handled according to the task `error_strategy`.
 
 Options
 -------

docs/reference/transformers/recursive_property_setter_transformer.md

@@ -56,6 +56,6 @@ Notes
 
 Keys of `set_properties` are property paths written with the PropertyAccessor on each item: use the `[key]` notation
 for array items and the `property` notation for objects. For `\stdClass` items, a property that cannot be written is
-added to the object.
+added to the object itself (a nested path such as `parent.id` is added as a `parent.id` property).
 
 Object items are modified in place, so the objects of the input are modified too.

docs/reference/transformers/slugify_transformer.md

@@ -58,3 +58,5 @@ Notes
 An invalid `transliterator` identifier (rejected by `\Transliterator::create()`), or an option that is not a string,
 raises an `InvalidOptionsException` when the options are resolved, i.e. when the transformer is configured, not on the
 first transformed value.
+
+A value that cannot be transliterated (e.g. invalid UTF-8) throws an `\UnexpectedValueException`.

docs/reference/transformers/xpath_evaluator_transformer.md

@@ -17,7 +17,8 @@ Transformer reference
 Accepted inputs
 ---------------
 
-`\DOMNode` (including `\DOMDocument`). Any other value throws an `\UnexpectedValueException`.
+`\DOMNode` (including `\DOMDocument`). Any other value, a node that does not belong to a document or an invalid xpath
+query throws an `\UnexpectedValueException`.
 
 Possible outputs
 ----------------

phpstan.neon

@@ -1,5 +1,5 @@
 parameters:
-    level: 6
+    level: 7
     paths:
         - src
         - tests