#357 - Documentation: fix the reference pages and the upgrade guide

CHANGELOG.md

@@ -4,6 +4,7 @@ Latest
 ## Changes
 * [#339](https://github.com/cleverage/process-bundle/issues/339) A shared service referenced by several tasks of the same process is rejected when the container is compiled (`InvalidArgumentException` naming the service, the tasks and the process): all these tasks ran with the same instance, initialized with the options of each task in turn, without error. Declare the task services with `shared: false` (applied by the autoconfiguration of `TaskInterface` since 5.4). Update documentation, add tests.
 * [#351](https://github.com/cleverage/process-bundle/issues/351) `ProcessManager` and `ProcessHelpCommand` are typed on `TaskRegistryInterface` instead of the final `TaskRegistry` class: the task registry can be decorated or replaced. Add tests.
+* [#357](https://github.com/cleverage/process-bundle/issues/357) Documentation: input of `file_splitter`, `log_empty_lines` of the CSV readers, empty lines of the line readers, invalid regular expressions of the conditions, cache pool of the `cached` transformer, missing serializer / validator, exceptions of the bundle in the reference pages, failure of a sub-process of `process_executor`, `sleep_on_finalize_interval` of `process_launcher`, initialization failures, `process_options` of `process_launcher` in `UPGRADE.md`.
 
 ## Fixes
 * [#343](https://github.com/cleverage/process-bundle/issues/343) The temporary files of `FileSplitterTask` (`file_splitter`), `CsvSplitterTask` (`csv_splitter`) and of the JSON buffer of `ProcessLauncherTask` (`json_buffering`) are created with a random name, exclusively (an existing path, symbolic links included, is never reused) and readable by their owner only, instead of a name derived from the time (`uniqid()`), opened in `w` mode with the permissions of the umask. Update documentation, add tests.

UPGRADE.md

@@ -131,6 +131,11 @@ for such a task is deprecated, listen to the `event_name` instead.
 When the initialization of a task fails, the process goes on with a deprecation. In 6.0, it will fail before executing
 any task.
 
+### Process launcher task
+
+The `process_options` option of the `process_launcher` task is deprecated (any non-empty value already throws an
+exception): remove it from your configurations, it will be removed in 6.0.
+
 ## v2.0.4
 
 ### Callback transformer

docs/04-advanced_workflow.md

@@ -31,7 +31,9 @@ The exceptions thrown by the bundle implement `CleverAge\ProcessBundle\Exception
 the `UnexpectedValueException`, `RuntimeException`, `InvalidArgumentException` and `LogicException` of the same
 namespace, which extend the SPL exceptions thrown before), so that they can all be caught at once. Not concerned: the
 exceptions of the Symfony components (e.g. `InvalidOptionsException` for an invalid task option) and the ones of your
-own tasks and transformers.
+own tasks and transformers. The reference pages name these exceptions without their namespace (e.g.
+`UnexpectedValueException`). In a chain of transformers, the exception of a transformer is wrapped in a
+`TransformerException` (see [TransformerTrait](reference/traits/transformer_trait.md)).
 
 ### Executing a process from PHP
 

docs/reference/02-task_definition.md

@@ -36,7 +36,7 @@ of its code: its service id, with or without a leading `@` (quote the value when
 e.g. `service: '@CleverAge\ProcessBundle\Task\TransformerTask'` (the tasks of this bundle have their class name as
 service id). The service must implement `CleverAge\ProcessBundle\Model\TaskInterface`. With an unknown service, a
 reference with `@` throws the `ServiceNotFoundException` of the service container, a reference without `@` an
-`\UnexpectedValueException` (`Unable to resolve service reference for Task '<task code>'`). A task defines either `task`
+`UnexpectedValueException` (`Unable to resolve service reference for Task '<task code>'`). A task defines either `task`
 or `service`, not both.
 
 Only a service that is not referenced by the configurations known when the container is compiled (e.g. a configuration

docs/reference/tasks/array_merge_task.md

@@ -14,7 +14,7 @@ Task reference
 Accepted inputs
 ---------------
 
-`array`: any other type throws an `\UnexpectedValueException`
+`array`: any other type throws an `UnexpectedValueException`
 
 Possible outputs
 ----------------

docs/reference/tasks/column_aggregator_task.md

@@ -35,7 +35,7 @@ Options
 | `reference_key`   | `string` |          | `column` | Key holding the column name in each output group                                                                                                |
 | `aggregation_key` | `string` |          | `values` | Key holding the aggregated rows in each output group                                                                                            |
 | `condition`       | `array`  |          | `[]`     | Conditions (`match`, `not_match`, `empty`, `not_empty`, `match_regexp`, `not_match_regexp`), see [ConditionTrait](../traits/condition_trait.md) |
-| `ignore_missing`  | `bool`   |          | `false`  | If `true`, missing columns only log a warning instead of throwing an `\UnexpectedValueException`                                                |
+| `ignore_missing`  | `bool`   |          | `false`  | If `true`, missing columns only log a warning instead of throwing an `UnexpectedValueException`                                                |
 
 The condition is checked, for each column, against an array with two keys: `input_column_value` (the value of the
 column) and `input` (the whole row). Use property paths such as `[input_column_value]` or `[input][status]`.

docs/reference/tasks/csv_reader_task.md

@@ -36,7 +36,7 @@ Options
 | `escape`          | `string`      |          | `\`     | CSV escape character                                                                                                              |
 | `headers`         | `array\|null` |          | `null`  | Static list of CSV headers. If `null`, headers are read from the first line of the file; otherwise the first line is read as data |
 | `mode`            | `string`      |          | `rb`    | File open mode (see [fopen mode parameter](https://www.php.net/manual/en/function.fopen.php))                                     |
-| `log_empty_lines` | `bool`        |          | `false` | Log a warning when a line cannot be read (empty line); cast to `bool`                                                             |
+| `log_empty_lines` | `bool`        |          | `false` | Log a warning when an empty read ends the file (e.g. the line break at the end of the last line). A blank line in the middle of the file is not skipped: it fails with "Number of columns not matching" (unless the file has a single column); cast to `bool` |
 
 Examples
 --------
@@ -70,9 +70,9 @@ entry:
 Notes
 -----
 
-* Each line must contain exactly as many columns as there are headers, otherwise an `\UnexpectedValueException` is thrown.
+* 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. If the first line is blank, an
-  `\UnexpectedValueException` is thrown.
+  `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

@@ -75,8 +75,8 @@ Notes
 -----
 
 * `{date}` is replaced by `Ymd`, `{date_time}` by `Ymd_His`, `{timestamp}` by the Unix timestamp and `{unique_token}`
-  by a `uniqid()` value.
+  by a `uniqid('', true)` value (23 characters, containing a dot).
 * The parent directory of the file is created if needed.
-* An input that is not an `array` throws an `\UnexpectedValueException`.
+* 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.
+  headers), otherwise an `UnexpectedValueException` is thrown. Columns are written in the headers order.

docs/reference/tasks/denormalizer_task.md

@@ -4,6 +4,8 @@ DenormalizerTask
 Denormalizes the input (usually an array) into an object of the configured class, using the Symfony Serializer
 `DenormalizerInterface`.
 
+Requires the Symfony serializer (`framework.serializer`): without it, the task fails with an explicit message.
+
 Task reference
 --------------
 

docs/reference/tasks/deserializer_task.md

@@ -3,6 +3,8 @@ DeserializerTask
 
 Deserializes a string input into a PHP value (object, array...) using the Symfony Serializer `SerializerInterface`.
 
+Requires the Symfony serializer (`framework.serializer`): without it, the task fails with an explicit message.
+
 Task reference
 --------------
 

docs/reference/tasks/event_dispatcher_task.md

@@ -72,7 +72,7 @@ public function onDataQueue(EventDispatcherTaskEvent $event): void
 `ProcessState` of every event in memory. Injecting or fetching this service triggers an `E_USER_DEPRECATED` error: write
 your own listener, as above.
 
-**Deprecated since v5, removed in v6.0**: from v4.0 to v5.0, the `event_name` option was ignored and the event was
+**Deprecated since v5.1 (deprecation notice), removed in v6.0**: from v4.0 to v5.0, the `event_name` option was ignored and the event was
 always dispatched under its class name. To preserve backward compatibility, when `event_name` is set (and differs from the
 event class name) and listeners subscribe to `CleverAge\ProcessBundle\Event\EventDispatcherTaskEvent`, the event is also
 dispatched under its class name and an `E_USER_DEPRECATED` error is triggered. In v6.0, listen to the configured

docs/reference/tasks/file_mover_task.md

@@ -13,7 +13,7 @@ Task reference
 Accepted inputs
 ---------------
 
-`string`: path of the file to move. An `\UnexpectedValueException` is thrown if it does not exist.
+`string`: path of the file to move. An `UnexpectedValueException` is thrown if it does not exist.
 
 Possible outputs
 ----------------

docs/reference/tasks/file_reader_task.md

@@ -25,7 +25,7 @@ Options
 
 | Code       | Type     | Required | Default | Description                                                                                                      |
 |------------|----------|:--------:|---------|------------------------------------------------------------------------------------------------------------------|
-| `filename` | `string` |  **X**   |         | Path of the file to read. An `\UnexpectedValueException` is thrown if the file does not exist or is not readable |
+| `filename` | `string` |  **X**   |         | Path of the file to read. An `UnexpectedValueException` is thrown if the file does not exist or is not readable |
 
 Examples
 --------

docs/reference/tasks/file_splitter_task.md

@@ -14,8 +14,10 @@ Task reference
 Accepted inputs
 ---------------
 
-`array`: optional, merged over the task options (e.g. `{ file_path: ..., max_lines: ... }`), which allows to give the
-file path as input. Any other input is ignored.
+`array`: optional, its `file_path` and `max_lines` values replace the ones of the task options (e.g.
+`{ file_path: ..., max_lines: ... }`). The `file_path` option is still required in the task configuration (the options
+are resolved before the input is merged): to give the file path as input only, set a placeholder value in the options.
+Any other input is ignored.
 
 Possible outputs
 ----------------

docs/reference/tasks/folder_browser_task.md

@@ -30,7 +30,7 @@ Options
 
 | Code              | Type                  | Required | Default   | Description                                                                                                    |
 |-------------------|-----------------------|:--------:|-----------|----------------------------------------------------------------------------------------------------------------|
-| `folder_path`     | `string`              |  **X**   |           | Path of the folder to browse. Must be an existing readable directory (checked at initialization)               |
+| `folder_path`     | `string`              |  **X**   |           | Path of the folder to browse. Must be an existing readable directory (checked at initialization; with process-bundle v5, the process fails when the task is first executed, see [initializable tasks](../../02-task_types.md#initializable-tasks))               |
 | `name_pattern`    | `string\|array\|null` |          | `null`    | Restrict files by name using a pattern (glob, regexp or string) or an array of patterns (see `Finder::name()`) |
 | `empty_log_level` | `string`              |          | `warning` | Log level used when no file is found, one of the `Psr\Log\LogLevel` constants                                  |
 

docs/reference/tasks/input_aggregator_task.md

@@ -18,7 +18,7 @@ Accepted inputs
 ---------------
 
 `any`: the parent task (previous task) code must be declared in `input_codes`, otherwise an
-`\UnexpectedValueException` is thrown. The task cannot be used without a previous task (e.g. as an entry point).
+`UnexpectedValueException` is thrown. The task cannot be used without a previous task (e.g. as an entry point).
 
 Possible outputs
 ----------------

docs/reference/tasks/input_csv_reader_task.md

@@ -38,7 +38,7 @@ Options
 | `escape`          | `string`      |          | `\`     | CSV escape character                                                                                                              |
 | `headers`         | `array\|null` |          | `null`  | Static list of CSV headers. If `null`, headers are read from the first line of the file; otherwise the first line is read as data |
 | `mode`            | `string`      |          | `rb`    | File open mode (see [fopen mode parameter](https://www.php.net/manual/en/function.fopen.php))                                     |
-| `log_empty_lines` | `bool`        |          | `false` | Log a warning when a line cannot be read (empty line)                                                                             |
+| `log_empty_lines` | `bool`        |          | `false` | Log a warning when an empty read ends the file (e.g. the line break at the end of the last line). A blank line in the middle of the file is not skipped: it fails with "Number of columns not matching" (unless the file has a single column) |
 
 The `file_path` option of [CsvReaderTask](csv_reader_task.md) is removed: the path comes from the input.
 

docs/reference/tasks/input_file_reader_task.md

@@ -13,7 +13,7 @@ Task reference
 Accepted inputs
 ---------------
 
-`string`: path of the file to read. An `\UnexpectedValueException` is thrown if the input is not a non-empty string
+`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/input_folder_browser_task.md

@@ -20,8 +20,8 @@ directory.
 
 The folder path is released once its files have all been iterated, so each input (the same path again or a different
 one) is browsed from the start. Receiving a different folder path while an iteration is in progress throws a
-`\LogicException`, and an empty input (`null`, `''`) when no folder is being browsed throws an
-`\UnexpectedValueException`.
+`LogicException`, and an empty input (`null`, `''`) when no folder is being browsed throws an
+`UnexpectedValueException`.
 
 Possible outputs
 ----------------

docs/reference/tasks/input_iterator_task.md

@@ -13,7 +13,7 @@ Task reference
 Accepted inputs
 ---------------
 
-`array`, `\Iterator` or `\IteratorAggregate` (whatever `\Traversable` its `getIterator()` returns): any other type throws an `\UnexpectedValueException`
+`array`, `\Iterator` or `\IteratorAggregate` (whatever `\Traversable` its `getIterator()` returns): any other type throws an `UnexpectedValueException`
 
 Possible outputs
 ----------------

docs/reference/tasks/input_line_reader_task.md

@@ -14,7 +14,7 @@ Task reference
 Accepted inputs
 ---------------
 
-`string`: path of the file to read. An `\UnexpectedValueException` is thrown if the file does not exist or is not
+`string`: path of the file to read. An `UnexpectedValueException` is thrown if the file does not exist or is not
 readable. The file is released once fully read, so each input (the same path again or a different one) is read from
 its beginning.
 
@@ -23,7 +23,8 @@ Possible outputs
 
 `string`: for each line, its raw content. The line break is not removed.
 Underlying class is [SplFileObject](https://www.php.net/manual/en/class.splfileobject.php), with the `READ_AHEAD` and
-`SKIP_EMPTY` flags.
+`SKIP_EMPTY` flags. Without `DROP_NEW_LINE`, the lines keep their line break, so an empty line is output as `"\n"`
+(only the empty string after the last line break is skipped).
 
 Options
 -------

docs/reference/tasks/json_stream_reader_task.md

@@ -25,7 +25,7 @@ Underlying methods are [SplFileObject::fgets](https://www.php.net/manual/en/splf
 
 When a line is empty or decodes to `null`, no output is produced and the task is skipped for this iteration. Each
 line must be a JSON object or array: a line decoding to a scalar (e.g. `42` or `"foo"`) raises an
-`\UnexpectedValueException` giving the line number and the file path.
+`UnexpectedValueException` giving the line number and the file path.
 
 Options
 -------

docs/reference/tasks/json_stream_writer_task.md

@@ -14,7 +14,7 @@ Task reference
 Accepted inputs
 ---------------
 
-`array`: data to encode. An `\UnexpectedValueException` is thrown for any other type.
+`array`: data to encode. An `UnexpectedValueException` is thrown for any other type.
 Underlying method is [json_encode](https://www.php.net/manual/en/function.json-encode.php).
 
 Possible outputs
@@ -60,7 +60,7 @@ Notes
 -----
 
 * `{date}` is replaced by `Ymd`, `{date_time}` by `Ymd_His`, `{timestamp}` by the Unix timestamp and `{unique_token}`
-  by a `uniqid()` value.
+  by a `uniqid('', true)` value (23 characters, containing a dot).
 * The parent directory of the file is created (recursively) if it does not exist.
 * Using `JSON_PRETTY_PRINT` produces multi-line documents: the file can no longer be read by
   [JsonStreamReaderTask](json_stream_reader_task.md).

docs/reference/tasks/line_reader_task.md

@@ -20,14 +20,15 @@ Possible outputs
 
 `string`: for each line, its raw content. The line break is not removed.
 Underlying class is [SplFileObject](https://www.php.net/manual/en/class.splfileobject.php), with the `READ_AHEAD` and
-`SKIP_EMPTY` flags.
+`SKIP_EMPTY` flags. Without `DROP_NEW_LINE`, the lines keep their line break, so an empty line is output as `"\n"`
+(only the empty string after the last line break is skipped).
 
 Options
 -------
 
 | Code       | Type     | Required | Default | Description                                                                                                      |
 |------------|----------|:--------:|---------|------------------------------------------------------------------------------------------------------------------|
-| `filename` | `string` |  **X**   |         | Path of the file to read. An `\UnexpectedValueException` is thrown if the file does not exist or is not readable |
+| `filename` | `string` |  **X**   |         | Path of the file to read. An `UnexpectedValueException` is thrown if the file does not exist or is not readable |
 
 Examples
 --------

docs/reference/tasks/normalizer_task.md

@@ -3,6 +3,8 @@ NormalizerTask
 
 Normalizes the input (usually an object) using the Symfony Serializer `NormalizerInterface`.
 
+Requires the Symfony serializer (`framework.serializer`): without it, the task fails with an explicit message.
+
 Task reference
 --------------
 
@@ -13,7 +15,7 @@ Accepted inputs
 ---------------
 
 `mixed`: any value supported by the normalizers for the given `format`. If no normalizer supports it, an
-`\UnexpectedValueException` is thrown.
+`UnexpectedValueException` is thrown.
 
 Possible outputs
 ----------------

docs/reference/tasks/object_updater_task.md

@@ -18,7 +18,7 @@ Accepted inputs
 * `object`: the object (or array) to update
 * `value`: the value to set
 
-An `\UnexpectedValueException` is thrown if one of these keys is missing.
+An `UnexpectedValueException` is thrown if one of these keys is missing.
 
 Possible outputs
 ----------------
@@ -30,7 +30,7 @@ Options
 
 | Code            | Type     | Required | Default | Description                                                 |
 |-----------------|----------|:--------:|---------|-------------------------------------------------------------|
-| `property_path` | `string` |  **X**   |         | Property path of the `object` where the `value` will be set |
+| `property_path` | `string\|PropertyPathInterface` |  **X**   |         | Property path of the `object` where the `value` will be set |
 
 Examples
 --------