From 65a0d6c4d0cd91cac3a2ac1d8beb58117eca494f Mon Sep 17 00:00:00 2001 From: Nicolas Joubert Date: Thu, 22 Oct 2026 18:46:43 +0200 Subject: [PATCH] #357 - Documentation: fix the reference pages and the upgrade guide (audit #93 to #110) Co-Authored-By: Claude Opus 5.5 (1M context) --- CHANGELOG.md | 3 +++ UPGRADE.md | 5 +++++ docs/04-advanced_workflow.md | 4 +++- docs/reference/02-task_definition.md | 2 +- docs/reference/tasks/array_merge_task.md | 2 +- docs/reference/tasks/column_aggregator_task.md | 2 +- docs/reference/tasks/csv_reader_task.md | 6 +++--- docs/reference/tasks/csv_writer_task.md | 6 +++--- docs/reference/tasks/denormalizer_task.md | 2 ++ docs/reference/tasks/deserializer_task.md | 2 ++ docs/reference/tasks/event_dispatcher_task.md | 2 +- docs/reference/tasks/file_mover_task.md | 2 +- docs/reference/tasks/file_reader_task.md | 2 +- docs/reference/tasks/file_splitter_task.md | 6 ++++-- docs/reference/tasks/folder_browser_task.md | 2 +- docs/reference/tasks/input_aggregator_task.md | 2 +- docs/reference/tasks/input_csv_reader_task.md | 2 +- docs/reference/tasks/input_file_reader_task.md | 2 +- docs/reference/tasks/input_folder_browser_task.md | 4 ++-- docs/reference/tasks/input_iterator_task.md | 2 +- docs/reference/tasks/input_line_reader_task.md | 5 +++-- docs/reference/tasks/json_stream_reader_task.md | 2 +- docs/reference/tasks/json_stream_writer_task.md | 4 ++-- docs/reference/tasks/line_reader_task.md | 5 +++-- docs/reference/tasks/normalizer_task.md | 4 +++- docs/reference/tasks/object_updater_task.md | 4 ++-- docs/reference/tasks/process_executor_task.md | 10 ++++++++++ docs/reference/tasks/process_launcher_task.md | 6 +++--- docs/reference/tasks/serializer_task.md | 2 ++ docs/reference/tasks/split_join_line_task.md | 2 +- docs/reference/tasks/validator_task.md | 4 +++- docs/reference/tasks/xml_reader_task.md | 4 ++-- docs/reference/tasks/xml_stream_reader_task.md | 4 ++-- docs/reference/tasks/xml_writer_task.md | 4 ++-- docs/reference/tasks/yaml_reader_task.md | 4 ++-- docs/reference/traits/condition_trait.md | 3 ++- .../reference/transformers/array_filter_transformer.md | 2 +- docs/reference/transformers/array_map_transformer.md | 2 +- docs/reference/transformers/array_unset_transformer.md | 2 +- docs/reference/transformers/cached_transformer.md | 5 +++-- docs/reference/transformers/date_format_transformer.md | 2 +- docs/reference/transformers/date_parser_transformer.md | 2 +- docs/reference/transformers/denormalize_transformer.md | 2 ++ docs/reference/transformers/implode_transformer.md | 2 +- docs/reference/transformers/instantiate_transformer.md | 2 +- docs/reference/transformers/mapping_transformer.md | 4 ++-- docs/reference/transformers/normalize_transformer.md | 2 ++ docs/reference/transformers/slugify_transformer.md | 2 +- .../transformers/xpath_evaluator_transformer.md | 6 +++--- src/Task/Process/ProcessLauncherTask.php | 2 +- 50 files changed, 102 insertions(+), 62 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9b33c604..9f31b13b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,9 @@ Latest ------ +## Changes +* [#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`. + v5.4.1 ----- diff --git a/UPGRADE.md b/UPGRADE.md index d6032acf..f4488cda 100644 --- a/UPGRADE.md +++ b/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 diff --git a/docs/04-advanced_workflow.md b/docs/04-advanced_workflow.md index 0c107e8e..261c63db 100644 --- a/docs/04-advanced_workflow.md +++ b/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 diff --git a/docs/reference/02-task_definition.md b/docs/reference/02-task_definition.md index 8c5f2ec1..d53f6a3d 100644 --- a/docs/reference/02-task_definition.md +++ b/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 ''`). A task defines either `task` +`UnexpectedValueException` (`Unable to resolve service reference for Task ''`). 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 diff --git a/docs/reference/tasks/array_merge_task.md b/docs/reference/tasks/array_merge_task.md index 489a6bd0..6f37126e 100644 --- a/docs/reference/tasks/array_merge_task.md +++ b/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 ---------------- diff --git a/docs/reference/tasks/column_aggregator_task.md b/docs/reference/tasks/column_aggregator_task.md index 6eaea8d7..f59931b8 100644 --- a/docs/reference/tasks/column_aggregator_task.md +++ b/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]`. diff --git a/docs/reference/tasks/csv_reader_task.md b/docs/reference/tasks/csv_reader_task.md index efa3d5c5..dc25c615 100644 --- a/docs/reference/tasks/csv_reader_task.md +++ b/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. diff --git a/docs/reference/tasks/csv_writer_task.md b/docs/reference/tasks/csv_writer_task.md index 83cb52d4..6b048128 100644 --- a/docs/reference/tasks/csv_writer_task.md +++ b/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. diff --git a/docs/reference/tasks/denormalizer_task.md b/docs/reference/tasks/denormalizer_task.md index 317e5b3f..68c1476f 100644 --- a/docs/reference/tasks/denormalizer_task.md +++ b/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 -------------- diff --git a/docs/reference/tasks/deserializer_task.md b/docs/reference/tasks/deserializer_task.md index 8161aef2..1fb53764 100644 --- a/docs/reference/tasks/deserializer_task.md +++ b/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 -------------- diff --git a/docs/reference/tasks/event_dispatcher_task.md b/docs/reference/tasks/event_dispatcher_task.md index 89d1acb3..75078e22 100644 --- a/docs/reference/tasks/event_dispatcher_task.md +++ b/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 diff --git a/docs/reference/tasks/file_mover_task.md b/docs/reference/tasks/file_mover_task.md index 0f4fa5e4..e6389ad9 100644 --- a/docs/reference/tasks/file_mover_task.md +++ b/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 ---------------- diff --git a/docs/reference/tasks/file_reader_task.md b/docs/reference/tasks/file_reader_task.md index f75e31c3..c710744b 100644 --- a/docs/reference/tasks/file_reader_task.md +++ b/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 -------- diff --git a/docs/reference/tasks/file_splitter_task.md b/docs/reference/tasks/file_splitter_task.md index 18282cf4..ebd40f7d 100644 --- a/docs/reference/tasks/file_splitter_task.md +++ b/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 ---------------- diff --git a/docs/reference/tasks/folder_browser_task.md b/docs/reference/tasks/folder_browser_task.md index 8cdca1b0..3b12b6ef 100644 --- a/docs/reference/tasks/folder_browser_task.md +++ b/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 | diff --git a/docs/reference/tasks/input_aggregator_task.md b/docs/reference/tasks/input_aggregator_task.md index b0fc1cfd..1b1cfea1 100644 --- a/docs/reference/tasks/input_aggregator_task.md +++ b/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 ---------------- diff --git a/docs/reference/tasks/input_csv_reader_task.md b/docs/reference/tasks/input_csv_reader_task.md index fed3844b..ba5c3750 100644 --- a/docs/reference/tasks/input_csv_reader_task.md +++ b/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. diff --git a/docs/reference/tasks/input_file_reader_task.md b/docs/reference/tasks/input_file_reader_task.md index e06754b5..3d50121e 100644 --- a/docs/reference/tasks/input_file_reader_task.md +++ b/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 diff --git a/docs/reference/tasks/input_folder_browser_task.md b/docs/reference/tasks/input_folder_browser_task.md index c8126305..35d82666 100644 --- a/docs/reference/tasks/input_folder_browser_task.md +++ b/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 ---------------- diff --git a/docs/reference/tasks/input_iterator_task.md b/docs/reference/tasks/input_iterator_task.md index 37cd862f..48e13366 100644 --- a/docs/reference/tasks/input_iterator_task.md +++ b/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 ---------------- diff --git a/docs/reference/tasks/input_line_reader_task.md b/docs/reference/tasks/input_line_reader_task.md index 682eff9f..51e1f260 100644 --- a/docs/reference/tasks/input_line_reader_task.md +++ b/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 ------- diff --git a/docs/reference/tasks/json_stream_reader_task.md b/docs/reference/tasks/json_stream_reader_task.md index b61db0ed..8c5810a0 100644 --- a/docs/reference/tasks/json_stream_reader_task.md +++ b/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 ------- diff --git a/docs/reference/tasks/json_stream_writer_task.md b/docs/reference/tasks/json_stream_writer_task.md index ffcc5c17..f9590b25 100644 --- a/docs/reference/tasks/json_stream_writer_task.md +++ b/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). diff --git a/docs/reference/tasks/line_reader_task.md b/docs/reference/tasks/line_reader_task.md index a9bb8d69..3915bb54 100644 --- a/docs/reference/tasks/line_reader_task.md +++ b/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 -------- diff --git a/docs/reference/tasks/normalizer_task.md b/docs/reference/tasks/normalizer_task.md index a07639dd..a1af8992 100644 --- a/docs/reference/tasks/normalizer_task.md +++ b/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 ---------------- diff --git a/docs/reference/tasks/object_updater_task.md b/docs/reference/tasks/object_updater_task.md index b636c6cb..9929ec9d 100644 --- a/docs/reference/tasks/object_updater_task.md +++ b/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 -------- diff --git a/docs/reference/tasks/process_executor_task.md b/docs/reference/tasks/process_executor_task.md index 5cfdfc98..49ca2699 100644 --- a/docs/reference/tasks/process_executor_task.md +++ b/docs/reference/tasks/process_executor_task.md @@ -44,3 +44,13 @@ run_subprocess: source: '{{ source }}' outputs: [next_task] ``` + +Notes +----- + +* When the sub-process fails, the `ProcessFailedException` is thrown by this task: its `error_strategy` applies. With + `stop` (default), the parent process fails too; with `skip`, the parent process goes on with the next input (the + input is sent to the `error_outputs` of the task, if any). +* The `process` option is checked when the task is initialized: with an unknown process, the initialization fails, the + error is logged and, with process-bundle v5, the parent process fails when the task is first executed (see + [initializable tasks](../../02-task_types.md#initializable-tasks)). diff --git a/docs/reference/tasks/process_launcher_task.md b/docs/reference/tasks/process_launcher_task.md index 9e3bec94..347c2cf4 100644 --- a/docs/reference/tasks/process_launcher_task.md +++ b/docs/reference/tasks/process_launcher_task.md @@ -30,7 +30,7 @@ finished, the task outputs the path of this file (`string`), during the next ite `json_buffering`, the task outputs nothing. If a sub-process exits with a non-zero code, its error output is logged as critical, all running sub-processes are -stopped and a `\RuntimeException` is thrown. +stopped and a `RuntimeException` is thrown. Options ------- @@ -41,10 +41,10 @@ Options | `max_processes` | `int` | | `3` | Maximum number of sub-processes running at the same time | | `sleep_interval` | `int\|float` | | `1` | Time (in seconds) to wait between two checks when the pool is full | | `sleep_interval_after_launch` | `int\|float` | | `1` | Time (in seconds) to wait after launching a sub-process | -| `sleep_on_finalize_interval` | `int\|float` | | `1` | Time (in seconds) to wait when the task has no finished result to output at the end of an iteration | +| `sleep_on_finalize_interval` | `int\|float` | | `1` | Time (in seconds) to wait at the end of **each** execution (each input) when no sub-process result is ready to be output, in addition to `sleep_interval_after_launch`: lower it to launch the sub-processes faster | | `context` | `array` | | `[]` | Context values passed to each sub-process (as `--context=key:value`, values must be scalars) | | `json_buffering` | `bool` | | `false` | Store each sub-process output in a JSON stream file and output its path | -| `process_options` | `array` | | `[]` | **Deprecated**: any non-empty value throws an `\InvalidArgumentException` | +| `process_options` | `array` | | `[]` | **Deprecated**: any non-empty value throws an `InvalidArgumentException` | Examples -------- diff --git a/docs/reference/tasks/serializer_task.md b/docs/reference/tasks/serializer_task.md index 7de1712f..9b738276 100644 --- a/docs/reference/tasks/serializer_task.md +++ b/docs/reference/tasks/serializer_task.md @@ -3,6 +3,8 @@ SerializerTask Serializes the input into a string of the given format using the Symfony Serializer `SerializerInterface`. +Requires the Symfony serializer (`framework.serializer`): without it, the task fails with an explicit message. + Task reference -------------- diff --git a/docs/reference/tasks/split_join_line_task.md b/docs/reference/tasks/split_join_line_task.md index eebda605..84f0216f 100644 --- a/docs/reference/tasks/split_join_line_task.md +++ b/docs/reference/tasks/split_join_line_task.md @@ -14,7 +14,7 @@ Task reference Accepted inputs --------------- -`array`: a line containing all the `split_columns` keys. An `\UnexpectedValueException` is thrown if one is missing. +`array`: a line containing all the `split_columns` keys. An `UnexpectedValueException` is thrown if one is missing. Possible outputs ---------------- diff --git a/docs/reference/tasks/validator_task.md b/docs/reference/tasks/validator_task.md index edc537dd..4fe57e76 100644 --- a/docs/reference/tasks/validator_task.md +++ b/docs/reference/tasks/validator_task.md @@ -3,6 +3,8 @@ ValidatorTask Validates the input with the Symfony Validator component and outputs it unchanged when it is valid. +Requires the Symfony validator (`framework.validation`): without it, the task fails with an explicit message. + Task reference -------------- @@ -24,7 +26,7 @@ When violations are found, each one is logged (if `log_errors` is enabled) with * if `error_output_violations` is `true`: the `ConstraintViolationListInterface` is sent to the error output and the task is skipped (nothing is sent to the outputs) -* otherwise: an `\UnexpectedValueException` is thrown (`N constraint violations detected on validation`), handled +* otherwise: an `UnexpectedValueException` is thrown (`N constraint violations detected on validation`), handled according to the task `error_strategy` Options diff --git a/docs/reference/tasks/xml_reader_task.md b/docs/reference/tasks/xml_reader_task.md index ce1324c1..23b708a4 100644 --- a/docs/reference/tasks/xml_reader_task.md +++ b/docs/reference/tasks/xml_reader_task.md @@ -44,8 +44,8 @@ read_xml: Notes ----- -* An empty file throws an `\UnexpectedValueException`. -* An invalid XML content (not well-formed, undefined namespace prefix...) throws an `\UnexpectedValueException` whose +* An empty file throws an `UnexpectedValueException`. +* An invalid XML content (not well-formed, undefined namespace prefix...) throws an `UnexpectedValueException` whose message contains the libxml error(s) with their line and column. libxml warnings are tolerated. The libxml internal errors setting is restored after loading. * The whole file is loaded in memory. Use [XmlStreamReaderTask](xml_stream_reader_task.md) to iterate over the elements diff --git a/docs/reference/tasks/xml_stream_reader_task.md b/docs/reference/tasks/xml_stream_reader_task.md index 810eef1b..6969ce65 100644 --- a/docs/reference/tasks/xml_stream_reader_task.md +++ b/docs/reference/tasks/xml_stream_reader_task.md @@ -66,10 +66,10 @@ Notes `node_name` nested inside a matching element is part of its parent output, and is not output on its own. * Namespaces declared on ancestors are copied to the expanded element, so prefixed queries (e.g. `g:price/text()`) still work. -* An invalid XML content (not well-formed, empty file...) throws an `\UnexpectedValueException` whose message contains +* An invalid XML content (not well-formed, empty file...) throws an `UnexpectedValueException` whose message contains the libxml error(s) with their line and column, handled by the task `error_strategy`. As the file is read as a stream, the elements located before the error have already been output. libxml warnings are tolerated. -* A missing or unreadable file, or no file path in the option nor in the input, throws an `\UnexpectedValueException`. +* A missing or unreadable file, or no file path in the option nor in the input, throws an `UnexpectedValueException`. * The file is released at the end of the iteration (and on `finalize()`), so that the task can read it again on its next input. * Use [XmlReaderTask](xml_reader_task.md) to get the whole document at once (small files). diff --git a/docs/reference/tasks/xml_writer_task.md b/docs/reference/tasks/xml_writer_task.md index 9da713a2..1c5ca035 100644 --- a/docs/reference/tasks/xml_writer_task.md +++ b/docs/reference/tasks/xml_writer_task.md @@ -14,7 +14,7 @@ Accepted inputs --------------- `\DOMDocument`: document to dump with [DOMDocument::saveXML](https://www.php.net/manual/en/domdocument.savexml.php). -An `\UnexpectedValueException` is thrown for any other type. +An `UnexpectedValueException` is thrown for any other type. Possible outputs ---------------- @@ -44,4 +44,4 @@ Notes ----- * The file is opened on each execution: with the default `wb` mode, each input overwrites the file. -* If the XML content cannot be generated (`\DOMDocument::saveXML()` fails) or written, a `\RuntimeException` is thrown. +* If the XML content cannot be generated (`\DOMDocument::saveXML()` fails) or written, a `RuntimeException` is thrown. diff --git a/docs/reference/tasks/yaml_reader_task.md b/docs/reference/tasks/yaml_reader_task.md index 56bd85a8..40bf778a 100644 --- a/docs/reference/tasks/yaml_reader_task.md +++ b/docs/reference/tasks/yaml_reader_task.md @@ -26,7 +26,7 @@ Options | Code | Type | Required | Default | Description | |-------------|----------|:--------:|---------|----------------------------------------------------------------------------------------------------------------------| -| `file_path` | `string` | **X** | | Path of the YAML file to read. An `\UnexpectedValueException` is thrown at initialization if the file does not exist | +| `file_path` | `string` | **X** | | Path of the YAML file to read. An `UnexpectedValueException` is thrown at initialization if the file does not exist (with process-bundle v5, the process fails when the task is first executed, see [initializable tasks](../../02-task_types.md#initializable-tasks)) | Examples -------- @@ -43,6 +43,6 @@ read_yaml: Notes ----- -* The root of the file must be a mapping or a sequence, otherwise an `\InvalidArgumentException` is thrown (e.g. for an +* The root of the file must be a mapping or a sequence, otherwise an `InvalidArgumentException` is thrown (e.g. for an empty file). An empty root mapping or sequence (`{}` or `[]`) produces no output: the task is skipped. * The current root key is added to the error context of the process as `iterator_key`. diff --git a/docs/reference/traits/condition_trait.md b/docs/reference/traits/condition_trait.md index 544c594e..90cfe915 100644 --- a/docs/reference/traits/condition_trait.md +++ b/docs/reference/traits/condition_trait.md @@ -28,7 +28,8 @@ Provide a configurable set of matching rules, used by tasks and transformers to | `match_regexp` | `array` | | `[]` | `path => pattern`: the value at `path`, cast to string, must match the regular expression | | `not_match_regexp` | `array` | | `[]` | `path => pattern`: the value at `path`, cast to string, must not match the regular expression | -An invalid regular expression makes both `match_regexp` and `not_match_regexp` fail. +An invalid regular expression makes both `match_regexp` and `not_match_regexp` fail. In debug mode, the PHP warning +of `preg_match()` is converted into an exception by the Symfony error handler: the task fails. ## Usage diff --git a/docs/reference/transformers/array_filter_transformer.md b/docs/reference/transformers/array_filter_transformer.md index 4480e66b..79d77695 100644 --- a/docs/reference/transformers/array_filter_transformer.md +++ b/docs/reference/transformers/array_filter_transformer.md @@ -13,7 +13,7 @@ Transformer reference Accepted inputs --------------- -`iterable` (`array` or `\Traversable`). Any other value throws an `\UnexpectedValueException`. +`iterable` (`array` or `\Traversable`). Any other value throws an `UnexpectedValueException`. Possible outputs ---------------- diff --git a/docs/reference/transformers/array_map_transformer.md b/docs/reference/transformers/array_map_transformer.md index a907d7dd..82917487 100644 --- a/docs/reference/transformers/array_map_transformer.md +++ b/docs/reference/transformers/array_map_transformer.md @@ -12,7 +12,7 @@ Transformer reference Accepted inputs --------------- -`array` or `\Traversable`. Any other value throws an `\UnexpectedValueException`. +`array` or `\Traversable`. Any other value throws an `UnexpectedValueException`. Possible outputs ---------------- diff --git a/docs/reference/transformers/array_unset_transformer.md b/docs/reference/transformers/array_unset_transformer.md index 23f72f53..73359f11 100644 --- a/docs/reference/transformers/array_unset_transformer.md +++ b/docs/reference/transformers/array_unset_transformer.md @@ -12,7 +12,7 @@ Transformer reference Accepted inputs --------------- -`array`. Any other value throws an `\UnexpectedValueException`. +`array`. Any other value throws an `UnexpectedValueException`. Possible outputs ---------------- diff --git a/docs/reference/transformers/cached_transformer.md b/docs/reference/transformers/cached_transformer.md index 19dffa16..125770e3 100644 --- a/docs/reference/transformers/cached_transformer.md +++ b/docs/reference/transformers/cached_transformer.md @@ -52,8 +52,9 @@ cached: Notes ----- -* The cache pool is the autowired `Psr\Cache\CacheItemPoolInterface` service (`cache.app` in a standard Symfony - application). Items are saved with `saveDeferred()`, a warning is logged if the save fails. +* The cache pool is the `cache.app` service, passed explicitly. To use another pool, override the `$cache` argument + of the `CleverAge\ProcessBundle\Transformer\CachedTransformer` service in your application + (`arguments: { $cache: '@cache.my_pool' }`). Items are saved with `saveDeferred()`, a warning is logged if the save fails. * A string `ttl` is converted to a date when the options are resolved (i.e. once, when the transformer is configured), not each time an item is saved: all items share the same absolute expiration date. * If the key value is not a string after `key_transformers` (e.g. an `int` input without a `cast` key transformer), diff --git a/docs/reference/transformers/date_format_transformer.md b/docs/reference/transformers/date_format_transformer.md index 9380f6e3..eeea9fcb 100644 --- a/docs/reference/transformers/date_format_transformer.md +++ b/docs/reference/transformers/date_format_transformer.md @@ -15,7 +15,7 @@ Accepted inputs * `\DateTimeInterface` (`\DateTime` or `\DateTimeImmutable`) * Any falsy value (`null`, `''`, `false`…), returned unchanged -Any other value (including a date string) throws an `\UnexpectedValueException`. Use +Any other value (including a date string) throws an `UnexpectedValueException`. Use [DateParserTransformer](date_parser_transformer.md) first to convert a string into a date. Possible outputs diff --git a/docs/reference/transformers/date_parser_transformer.md b/docs/reference/transformers/date_parser_transformer.md index 6163b639..f83e1333 100644 --- a/docs/reference/transformers/date_parser_transformer.md +++ b/docs/reference/transformers/date_parser_transformer.md @@ -17,7 +17,7 @@ Accepted inputs * `\DateTimeImmutable`, converted to a `\DateTime` (same date, time and timezone) * Any falsy value (`null`, `''`, `false`…), returned unchanged -A string that cannot be parsed with the given format throws an `\UnexpectedValueException`. +A string that cannot be parsed with the given format throws an `UnexpectedValueException`. Possible outputs ---------------- diff --git a/docs/reference/transformers/denormalize_transformer.md b/docs/reference/transformers/denormalize_transformer.md index 5883ff15..32093fad 100644 --- a/docs/reference/transformers/denormalize_transformer.md +++ b/docs/reference/transformers/denormalize_transformer.md @@ -4,6 +4,8 @@ DenormalizeTransformer Denormalize the input into an instance of the given class, using the Symfony [Serializer](https://symfony.com/doc/current/components/serializer.html) denormalizer. +Requires the Symfony serializer (`framework.serializer`): without it, the transformer fails with an explicit message. + See also [DenormalizerTask](../tasks/denormalizer_task.md) for the task equivalent. Transformer reference diff --git a/docs/reference/transformers/implode_transformer.md b/docs/reference/transformers/implode_transformer.md index 725493d1..f5a6da78 100644 --- a/docs/reference/transformers/implode_transformer.md +++ b/docs/reference/transformers/implode_transformer.md @@ -13,7 +13,7 @@ Transformer reference Accepted inputs --------------- -`array` of values that can be cast to `string`. Any other input throws an `\UnexpectedValueException`. +`array` of values that can be cast to `string`. Any other input throws an `UnexpectedValueException`. Possible outputs ---------------- diff --git a/docs/reference/transformers/instantiate_transformer.md b/docs/reference/transformers/instantiate_transformer.md index b6ce1c5d..c01410ea 100644 --- a/docs/reference/transformers/instantiate_transformer.md +++ b/docs/reference/transformers/instantiate_transformer.md @@ -14,7 +14,7 @@ Accepted inputs --------------- `array`: the constructor arguments. A list is passed positionally; string keys are used as named arguments. Any other -value throws an `\UnexpectedValueException`. +value throws an `UnexpectedValueException`. Possible outputs ---------------- diff --git a/docs/reference/transformers/mapping_transformer.md b/docs/reference/transformers/mapping_transformer.md index af877a5e..5ac76003 100644 --- a/docs/reference/transformers/mapping_transformer.md +++ b/docs/reference/transformers/mapping_transformer.md @@ -139,10 +139,10 @@ Notes * When a sub-transformer fails, the thrown `TransformerException` reports the target property. * On an array destination, a target property that is not an index notation is added as a literal key: a simple property name (e.g. `name`) gives the `name` key. Doing so with a nested path (e.g. `address.city`, `address[city]`) - is deprecated and will throw an `\UnexpectedValueException` in v6.0: use `[address.city]` to keep a literal key, or + is deprecated and will throw an `UnexpectedValueException` in v6.0: use `[address.city]` to keep a literal key, or `[address][city]` to write in a nested array. * A missing property of a `\stdClass` destination is added only for a simple target property name (e.g. `name`): a nested path (e.g. `address.city`) or an index notation (e.g. `[name]`) that is not writable throws an - `\UnexpectedValueException` (`Property '...' is not writable`), as for any other object. + `UnexpectedValueException` (`Property '...' is not writable`), as for any other object. * `merge_callback` receives the destination by value: to modify an array destination, the callable must take its first argument by reference. diff --git a/docs/reference/transformers/normalize_transformer.md b/docs/reference/transformers/normalize_transformer.md index 5389f3db..c873ccee 100644 --- a/docs/reference/transformers/normalize_transformer.md +++ b/docs/reference/transformers/normalize_transformer.md @@ -4,6 +4,8 @@ NormalizeTransformer Normalize the input (typically an object) into an array or a scalar, using the Symfony [Serializer](https://symfony.com/doc/current/components/serializer.html) normalizer. +Requires the Symfony serializer (`framework.serializer`): without it, the transformer fails with an explicit message. + See also [NormalizerTask](../tasks/normalizer_task.md) for the task equivalent. Transformer reference diff --git a/docs/reference/transformers/slugify_transformer.md b/docs/reference/transformers/slugify_transformer.md index a963f525..acad18d9 100644 --- a/docs/reference/transformers/slugify_transformer.md +++ b/docs/reference/transformers/slugify_transformer.md @@ -59,4 +59,4 @@ An invalid `transliterator` identifier (rejected by `\Transliterator::create()`) 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`. +A value that cannot be transliterated (e.g. invalid UTF-8) throws an `UnexpectedValueException`. diff --git a/docs/reference/transformers/xpath_evaluator_transformer.md b/docs/reference/transformers/xpath_evaluator_transformer.md index 3ed4609c..27d327f2 100644 --- a/docs/reference/transformers/xpath_evaluator_transformer.md +++ b/docs/reference/transformers/xpath_evaluator_transformer.md @@ -18,7 +18,7 @@ Accepted inputs --------------- `\DOMNode` (including `\DOMDocument`). Any other value, a node that does not belong to a document or an invalid xpath -query throws an `\UnexpectedValueException`. +query throws an `UnexpectedValueException`. Possible outputs ---------------- @@ -39,8 +39,8 @@ Options | Code | Type | Required | Default | Description | |------------------|-----------------|:--------:|---------|------------------------------------------------------------------------------------------------------------------------------------------| | `query` | `string\|array` | **X** | | An XPath query, or an array of subqueries (see below) | -| `single_result` | `bool` | | `true` | Return a single value instead of a list; more than one result throws an `\UnexpectedValueException` | -| `ignore_missing` | `bool` | | `true` | Only used with `single_result`: return `null` when nothing matches, instead of throwing an `\UnexpectedValueException` | +| `single_result` | `bool` | | `true` | Return a single value instead of a list; more than one result throws an `UnexpectedValueException` | +| `ignore_missing` | `bool` | | `true` | Only used with `single_result`: return `null` when nothing matches, instead of throwing an `UnexpectedValueException` | | `unwrap_value` | `bool` | | `true` | Return the text value of each result; only `\DOMText` (use the `text()` selector) and `\DOMAttr` results are supported, others throw | Each element of an array `query` is either a string (the subquery itself, using the root level options), or an array diff --git a/src/Task/Process/ProcessLauncherTask.php b/src/Task/Process/ProcessLauncherTask.php index 2d8a079f..6a9086a2 100644 --- a/src/Task/Process/ProcessLauncherTask.php +++ b/src/Task/Process/ProcessLauncherTask.php @@ -256,7 +256,7 @@ function (Options $options, $value) { 'process_options', static function (Options $options, array $value): array { if ([] !== $value) { - // Todo deprecation trigger + // Deprecated option, removed in v6.0: a non-empty value is not supported anymore throw new InvalidArgumentException('Deprecated option, please contact support for help'); }