From 1ee2a0e49b84a75a5cd409f0b96d1bc35cb21527 Mon Sep 17 00:00:00 2001 From: Nicolas Joubert Date: Thu, 22 Oct 2026 18:49:34 +0200 Subject: [PATCH] #62 - Cookbook: task codes instead of the deprecated `service:`, broken link; exceptions of the bundle in the reference pages Co-Authored-By: Claude Opus 5.5 (1M context) --- CHANGELOG.md | 3 +++ docs/cookbooks/export_archive_upload.md | 6 +++--- docs/index.md | 7 +++++++ docs/reference/tasks/unzip_task.md | 6 +++--- docs/reference/tasks/zip_task.md | 6 +++--- 5 files changed, 19 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ef6592d..703e081 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,9 @@ Latest ------ +### Changes +* [#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 ------ diff --git a/docs/cookbooks/export_archive_upload.md b/docs/cookbooks/export_archive_upload.md index 58f2297..c8bf3bc 100644 --- a/docs/cookbooks/export_archive_upload.md +++ b/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. diff --git a/docs/index.md b/docs/index.md index 173d2d3..2d19c42 100644 --- a/docs/index.md +++ b/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. diff --git a/docs/reference/tasks/unzip_task.md b/docs/reference/tasks/unzip_task.md index 97b36ed..7a91e97 100644 --- a/docs/reference/tasks/unzip_task.md +++ b/docs/reference/tasks/unzip_task.md @@ -18,7 +18,7 @@ configured ones. It may only contain the `filename` and/or `destination` keys (a `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 | Both options are required, but they can be provided either in the task configuration or in the input. @@ -78,7 +78,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 diff --git a/docs/reference/tasks/zip_task.md b/docs/reference/tasks/zip_task.md index da54b7c..f1e5270 100644 --- a/docs/reference/tasks/zip_task.md +++ b/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,7 +87,7 @@ 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 @@ -95,7 +95,7 @@ Notes `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.