#62 - Cookbook: task codes instead of the deprecated service:, broken link; exceptions of the bundle in the reference pages

CHANGELOG.md

@@ -3,6 +3,7 @@ Latest
 
 ### Changes
 * [#55](https://github.com/cleverage/archive-process-bundle/issues/55) `UnzipTask` (`archive_unzip`): new `max_files` and `max_size` options (default `null`, no limit) to protect the server against "zip bombs": the number of entries and their total uncompressed size are checked before anything is extracted, the task fails with a `RuntimeException` when a limit is exceeded. Update documentation, add tests.
+* [#62](https://github.com/cleverage/archive-process-bundle/issues/62) Cookbook: task codes instead of the deprecated `service:`, broken link; exceptions of the bundle in the reference pages.
 
 v2.3
 ------

docs/cookbooks/export_archive_upload.md

@@ -34,7 +34,7 @@ clever_age_process:
             help: 'bin/console cleverage:process:execute app.export_archive_upload'
             tasks:
                 read:
-                    service: '@CleverAge\DoctrineProcessBundle\Task\Database\DatabaseReaderTask'
+                    task: doctrine_database_reader
                     options:
                         table: 'book'
                         sql: 'SELECT b.id, b.title FROM book b ORDER BY b.id'
@@ -71,7 +71,7 @@ clever_age_process:
                     outputs: [upload]
 
                 upload:
-                    service: '@CleverAge\FlysystemProcessBundle\Task\FileFetchTask'
+                    task: flysystem_file_fetch
                     options:
                         source_filesystem: 'local.storage'
                         destination_filesystem: 'remote.storage'
@@ -101,7 +101,7 @@ How it works:
   the absolute path of the archive.
 - The [callback](https://github.com/cleverage/process-bundle/blob/main/docs/reference/transformers/callback_transformer.md)
   transformer turns this absolute path into a path relative to the `local.storage` root, as expected by the
-  [FileFetchTask](https://github.com/cleverage/flysystem-process-bundle/blob/main/docs/reference/tasks/01-FileFetchTask.md),
+  [FileFetchTask](https://github.com/cleverage/flysystem-process-bundle/blob/main/docs/reference/tasks/file_fetch_task.md),
   which copies the archive to `remote.storage` and removes the local one (`remove_source: true`).
 - The [LoggerTask](https://github.com/cleverage/process-bundle/blob/main/docs/reference/tasks/logger_task.md) logs the
   uploaded file name.

docs/index.md

@@ -54,3 +54,10 @@ No option can be configured under `cleverage_archive_process`: a key there is ig
         - [UnzipTask](reference/tasks/unzip_task.md)
         - [ZipTask](reference/tasks/zip_task.md)
     - [ProcessBundle documentation](https://github.com/cleverage/process-bundle/blob/main/docs/index.md)
+
+## Exceptions
+
+The exceptions named without namespace in the reference pages (e.g. `UnexpectedValueException`) are the ones of the
+bundle, `CleverAge\ArchiveProcessBundle\Exception\*`: they extend the SPL exceptions of the same name and implement
+`CleverAge\ProcessBundle\Exception\ProcessExceptionInterface`, so that all the errors of the process bundles can be
+caught at once.

docs/reference/tasks/unzip_task.md

@@ -18,7 +18,7 @@ configured ones. It may only contain option keys (`filename`, `destination`, `ma
 `UndefinedOptionsException`). A `null` input is handled as an empty array, so the options come from the task
 configuration only.
 
-Any other input type (e.g. a `string` file path) is not supported and throws an `\UnexpectedValueException`: convert it into an array first, for instance with a
+Any other input type (e.g. a `string` file path) is not supported and throws an `UnexpectedValueException`: convert it into an array first, for instance with a
 [TransformerTask](https://github.com/cleverage/process-bundle/blob/main/docs/reference/tasks/transformer_task.md) and
 the [wrapper](https://github.com/cleverage/process-bundle/blob/main/docs/reference/transformers/wrapper_transformer.md)
 transformer (`wrapper_key: filename`).
@@ -33,7 +33,7 @@ Options
 
 | Code          | Type     | Required | Default | Description                                                                                       |
 |---------------|----------|:--------:|---------|---------------------------------------------------------------------------------------------------|
-| `filename`    | `string` |  **X**   |         | Path of the zip archive to extract. It must exist and be readable (`\UnexpectedValueException`)   |
+| `filename`    | `string` |  **X**   |         | Path of the zip archive to extract. It must exist and be readable (`UnexpectedValueException`)   |
 | `destination` | `string` |  **X**   |         | Directory where the archive content is extracted                                                  |
 | `max_files`   | `?int`   |          | `null`  | Maximum number of entries of the archive (`null`: no limit)                                       |
 | `max_size`    | `?int`   |          | `null`  | Maximum total uncompressed size of the entries, in bytes (`null`: no limit)                       |
@@ -80,7 +80,7 @@ Notes
 * Underlying method is [ZipArchive::extractTo()](https://www.php.net/manual/en/ziparchive.extractto.php): the whole
   archive is extracted, existing files with the same name are overwritten and other files already present in the
   destination directory are kept.
-* A `\RuntimeException` is thrown if the file cannot be opened as a zip archive (with the `ZipArchive` error code,
+* A `RuntimeException` is thrown if the file cannot be opened as a zip archive (with the `ZipArchive` error code,
   e.g. `19` for `ZipArchive::ER_NOZIP`), or cannot be extracted (e.g. `destination` is not writable or is a file). In
   the latter case, the files extracted before the failure are kept.
 * Options are resolved on each execution of the task: when the task receives several inputs (e.g. after an iterable

docs/reference/tasks/zip_task.md

@@ -18,7 +18,7 @@ configured ones. It may only contain the `filename`, `files` and/or `files_base_
 `UndefinedOptionsException`). A `null` input is handled as an empty array, so the options come from the task
 configuration only.
 
-Any other input type (e.g. a `string` file path) is not supported and throws an `\UnexpectedValueException`: convert it into an array first, for instance with a
+Any other input type (e.g. a `string` file path) is not supported and throws an `UnexpectedValueException`: convert it into an array first, for instance with a
 [TransformerTask](https://github.com/cleverage/process-bundle/blob/main/docs/reference/tasks/transformer_task.md) and
 the [wrapper](https://github.com/cleverage/process-bundle/blob/main/docs/reference/transformers/wrapper_transformer.md)
 transformer (`wrapper_key: files`).
@@ -87,15 +87,15 @@ Notes
 -----
 
 * Underlying class is [ZipArchive](https://www.php.net/manual/en/class.ziparchive.php), the archive is opened with the
-  `ZipArchive::CREATE | ZipArchive::OVERWRITE` flags. A `\RuntimeException` is thrown if it cannot be opened (with the
+  `ZipArchive::CREATE | ZipArchive::OVERWRITE` flags. A `RuntimeException` is thrown if it cannot be opened (with the
   `ZipArchive` error code), or written once all files are added (e.g. when the parent directory of `filename` does not
   exist, the directory is not created).
 * For each file, the entry name is the file path with the leading `files_base_path` removed (only when the path starts
   with it, followed by a directory separator) and leading directory separators trimmed; the file actually read is
   `files_base_path` + directory separator + entry name. Hence all files must be located under `files_base_path`.
 * With the default empty `files_base_path`, the file is read at the given path (absolute, or relative to the current
   directory), and the entries keep this path (without the leading `/`) inside the archive.
-* Each file must exist and be readable, otherwise an `\UnexpectedValueException` is thrown. Only files can be added:
+* Each file must exist and be readable, otherwise an `UnexpectedValueException` is thrown. Only files can be added:
   directories are not browsed.
 * Options are resolved on each execution of the task: when the task receives several inputs (e.g. after an iterable
   task), each input creates its own archive. To archive a list of files in a single archive, aggregate them first (e.g.