#31 - Give a code to the tasks, class name as service id

CHANGELOG.md

@@ -2,6 +2,7 @@ Latest
 ------
 
 ### Changes
+* [#31](https://github.com/cleverage/archive-process-bundle/issues/31) Give a code to the tasks ([cleverage/process-bundle#91](https://github.com/cleverage/process-bundle/issues/91)): `archive_zip` and `archive_unzip` (`task: archive_zip`, with `cleverage/process-bundle` 5.4 or later, referencing them by `service` being deprecated there). The tasks have their class name as service id; fetching them directly from the service container is deprecated (`container.private`), they will be private in 3.0. The former ids `cleverage_archive_process.task.zip` / `cleverage_archive_process.task.unzip` are deprecated aliases, removed in 3.0. Update documentation, add tests.
 * [#29](https://github.com/cleverage/archive-process-bundle/issues/29) CI: test the lowest versions allowed by `composer.json` (`--prefer-lowest`, PHP 8.2).
 * [#27](https://github.com/cleverage/archive-process-bundle/issues/27) Add a `.gitattributes`: the development files (`.docker/`, `.github/`, `tests/`, quality tools and PHPUnit configurations, `Makefile`) are no longer part of the archive installed by Composer (`dist`).
 

config/services/task.yaml

@@ -1,14 +1,30 @@
 services:
-    cleverage_archive_process.task.unzip:
-        class: CleverAge\ArchiveProcessBundle\Task\UnzipTask
-        shared: false
-    CleverAge\ArchiveProcessBundle\Task\UnzipTask:
-        alias: cleverage_archive_process.task.unzip
+    _defaults:
+        # Public for the direct access from the service container, deprecated since 2.3: private in 3.0
         public: true
+        tags:
+            - { name: container.private, package: cleverage/archive-process-bundle, version: '2.3' }
 
-    cleverage_archive_process.task.zip:
-        class: CleverAge\ArchiveProcessBundle\Task\ZipTask
+    CleverAge\ArchiveProcessBundle\Task\UnzipTask:
         shared: false
+        tags:
+            - { name: cleverage.task, code: archive_unzip }
+    cleverage_archive_process.task.unzip:
+        alias: CleverAge\ArchiveProcessBundle\Task\UnzipTask
+        public: false
+        deprecated:
+            package: cleverage/archive-process-bundle
+            version: '2.3'
+            message: 'The "%alias_id%" service alias is deprecated, use the "archive_unzip" task code or the class name of the task instead. It will be removed in 3.0.'
+
     CleverAge\ArchiveProcessBundle\Task\ZipTask:
-        alias: cleverage_archive_process.task.zip
-        public: true
+        shared: false
+        tags:
+            - { name: cleverage.task, code: archive_zip }
+    cleverage_archive_process.task.zip:
+        alias: CleverAge\ArchiveProcessBundle\Task\ZipTask
+        public: false
+        deprecated:
+            package: cleverage/archive-process-bundle
+            version: '2.3'
+            message: 'The "%alias_id%" service alias is deprecated, use the "archive_zip" task code or the class name of the task instead. It will be removed in 3.0.'

docs/cookbooks/export_archive_upload.md

@@ -41,29 +41,29 @@ clever_age_process:
                     outputs: [write]
 
                 write:
-                    service: '@CleverAge\ProcessBundle\Task\File\Csv\CsvWriterTask'
+                    task: csv_writer
                     options:
                         file_path: '%kernel.project_dir%/var/exports/books_{date}.csv'
                         headers: [id, title]
                     outputs: [to_zip_input]
 
                 to_zip_input:
-                    service: '@CleverAge\ProcessBundle\Task\TransformerTask'
+                    task: transformer
                     options:
                         transformers:
                             wrapper:
                                 wrapper_key: files # '/.../books_20260930.csv' => { files: '/.../books_20260930.csv' }
                     outputs: [zip]
 
                 zip:
-                    service: '@CleverAge\ArchiveProcessBundle\Task\ZipTask'
+                    task: archive_zip
                     options:
                         filename: '%kernel.project_dir%/var/storage/local/books.zip' # Inside the local.storage root
                         files_base_path: '%kernel.project_dir%/var/exports' # The archive entry is 'books_20260930.csv'
                     outputs: [to_storage_path]
 
                 to_storage_path:
-                    service: '@CleverAge\ProcessBundle\Task\TransformerTask'
+                    task: transformer
                     options:
                         transformers:
                             callback:
@@ -79,7 +79,7 @@ clever_age_process:
                     outputs: [log_upload]
 
                 log_upload:
-                    service: '@CleverAge\ProcessBundle\Task\Reporting\LoggerTask'
+                    task: logger
                     options:
                         level: info
                         message: 'Archive uploaded'

docs/cookbooks/import_archive.md

@@ -25,36 +25,36 @@ clever_age_process:
                                   context: ~
             tasks:
                 prepare:
-                    service: '@CleverAge\ProcessBundle\Task\TransformerTask'
+                    task: transformer
                     options:
                         transformers:
                             wrapper:
                                 wrapper_key: filename # '/path/to/archive.zip' => { filename: '/path/to/archive.zip' }
                     outputs: [unzip]
 
                 unzip:
-                    service: '@CleverAge\ArchiveProcessBundle\Task\UnzipTask'
+                    task: archive_unzip
                     options:
                         destination: '%kernel.project_dir%/var/imports/archive'
                     outputs: [browse]
 
                 browse:
-                    service: '@CleverAge\ProcessBundle\Task\File\InputFolderBrowserTask'
+                    task: input_folder_browser
                     options:
                         name_pattern: '*.csv'
                     outputs: [read]
 
                 read:
-                    service: '@CleverAge\ProcessBundle\Task\File\Csv\InputCsvReaderTask'
+                    task: input_csv_reader
                     options:
                         delimiter: ';'
                     outputs: [count_rows, log_row]
 
                 count_rows:
-                    service: '@CleverAge\ProcessBundle\Task\Reporting\StatCounterTask'
+                    task: stat_counter
 
                 log_row:
-                    service: '@CleverAge\ProcessBundle\Task\Reporting\LoggerTask'
+                    task: logger
                     options:
                         level: info
                         message: 'Imported line' # Replace this task by your own transformation / loading tasks

docs/index.md

@@ -29,8 +29,15 @@ CleverAge\ArchiveProcessBundle\CleverAgeArchiveProcessBundle::class => ['all' =>
 
 ## Configuration
 
-This bundle has no configuration: its tasks are registered as services (public, non-shared) and can be used directly
-in your processes by referencing their class name, e.g. `service: '@CleverAge\ArchiveProcessBundle\Task\ZipTask'`.
+This bundle has no configuration: its tasks are registered as services (non-shared) and are used in your processes by
+their code, `archive_zip` and `archive_unzip` (e.g. `task: archive_zip`, requires `cleverage/process-bundle` 5.4 or
+later, see its [task definition](https://github.com/cleverage/process-bundle/blob/main/docs/reference/02-task_definition.md)).
+Referencing them by their class name (`service: '@CleverAge\ArchiveProcessBundle\Task\ZipTask'`) is deprecated since
+`cleverage/process-bundle` 5.4.
+
+Their service id is their class name. Fetching them directly from the service container is deprecated since 2.3 (they
+will be private in 3.0); their former ids, `cleverage_archive_process.task.zip` and
+`cleverage_archive_process.task.unzip`, are deprecated aliases since 2.3, removed in 3.0.
 
 Both tasks accept their options either from the task configuration or from their input (an array merged with the
 options), which allows computing paths in a previous task.

docs/reference/tasks/_template.md

@@ -7,6 +7,7 @@ Task reference
 --------------
 
 * **Service**: `Fully\Qualified\ClassName`
+* **Code**: `archive_task_code` (`task: archive_task_code`)
 * **Iterable task** _(only if it implements `IterableTaskInterface`)_
 * **Blocking task** _(only if it implements `BlockingTaskInterface`)_
 * **Flushable task** _(only if it implements `FlushableTaskInterface`)_
@@ -39,7 +40,7 @@ Examples
 ```yaml
 # Task configuration level
 code:
-  service: '@Fully\Qualified\ClassName'
+  task: task_code
   options:
     a: 1
     b: 2

docs/reference/tasks/unzip_task.md

@@ -8,6 +8,7 @@ Task reference
 --------------
 
 * **Service**: `CleverAge\ArchiveProcessBundle\Task\UnzipTask`
+* **Code**: `archive_unzip` (`task: archive_unzip`)
 
 Accepted inputs
 ---------------
@@ -46,7 +47,7 @@ Examples
 ```yaml
 # Task configuration level
 unzip:
-  service: '@CleverAge\ArchiveProcessBundle\Task\UnzipTask'
+  task: archive_unzip
   options:
     filename: '%kernel.project_dir%/var/data/archive.zip'
     destination: '%kernel.project_dir%/var/data/unzip_archive'
@@ -58,17 +59,17 @@ unzip:
 ```yaml
 # Task configuration level
 entry:
-  service: '@CleverAge\ProcessBundle\Task\ConstantOutputTask'
+  task: constant_output
   options:
     output:
       filename: '%kernel.project_dir%/var/data/archive.zip'
       destination: '%kernel.project_dir%/var/data/unzip_archive'
   outputs: [unzip]
 unzip:
-  service: '@CleverAge\ArchiveProcessBundle\Task\UnzipTask'
+  task: archive_unzip
   outputs: [browse]
 browse:
-  service: '@CleverAge\ProcessBundle\Task\File\InputFolderBrowserTask'
+  task: input_folder_browser
 ```
 
 Notes

docs/reference/tasks/zip_task.md

@@ -8,6 +8,7 @@ Task reference
 --------------
 
 * **Service**: `CleverAge\ArchiveProcessBundle\Task\ZipTask`
+* **Code**: `archive_zip` (`task: archive_zip`)
 
 Accepted inputs
 ---------------
@@ -47,7 +48,7 @@ Examples
 ```yaml
 # Task configuration level
 zip:
-  service: '@CleverAge\ArchiveProcessBundle\Task\ZipTask'
+  task: archive_zip
   options:
     filename: '%kernel.project_dir%/var/data/zip_archive.zip'
     files:
@@ -64,19 +65,19 @@ zip:
 ```yaml
 # Task configuration level
 write:
-  service: '@CleverAge\ProcessBundle\Task\File\Csv\CsvWriterTask'
+  task: csv_writer
   options:
     file_path: '%kernel.project_dir%/var/exports/books_{date}.csv'
   outputs: [to_zip_input]
 to_zip_input:
-  service: '@CleverAge\ProcessBundle\Task\TransformerTask'
+  task: transformer
   options:
     transformers:
       wrapper:
         wrapper_key: files # 'path/to/books_20260930.csv' => { files: 'path/to/books_20260930.csv' }
   outputs: [zip]
 zip:
-  service: '@CleverAge\ArchiveProcessBundle\Task\ZipTask'
+  task: archive_zip
   options:
     filename: '%kernel.project_dir%/var/exports/books.zip'
     files_base_path: '%kernel.project_dir%/var/exports'

tests/DependencyInjection/CleverAgeArchiveProcessExtensionTest.php

@@ -25,31 +25,41 @@
 class CleverAgeArchiveProcessExtensionTest extends TestCase
 {
     /**
-     * @return iterable<string, array{string, class-string}>
+     * @return iterable<string, array{class-string, string, string}>
      */
     public static function provideTasks(): iterable
     {
-        yield 'zip' => ['cleverage_archive_process.task.zip', ZipTask::class];
-        yield 'unzip' => ['cleverage_archive_process.task.unzip', UnzipTask::class];
+        yield 'zip' => [ZipTask::class, 'archive_zip', 'cleverage_archive_process.task.zip'];
+        yield 'unzip' => [UnzipTask::class, 'archive_unzip', 'cleverage_archive_process.task.unzip'];
     }
 
     /**
      * @param class-string $class
      */
     #[DataProvider('provideTasks')]
-    public function testTaskIsRegistered(string $id, string $class): void
+    public function testTaskIsRegistered(string $class, string $code, string $deprecatedId): void
     {
         $container = new ContainerBuilder();
         (new CleverAgeArchiveProcessExtension())->load([], $container);
 
-        $definition = $container->getDefinition($id);
-        self::assertSame($class, $definition->getClass());
+        // The class name is the service id
+        $definition = $container->getDefinition($class);
         // Tasks are stateful: each process execution must get its own instance
         self::assertFalse($definition->isShared());
+        // Referenced by its code in the process configurations (task: <code>)
+        self::assertSame([['code' => $code]], $definition->getTag('cleverage.task'));
+        // Public for the direct access from the service container, deprecated
+        self::assertTrue($definition->isPublic());
+        self::assertSame([['package' => 'cleverage/archive-process-bundle', 'version' => '2.3']], $definition->getTag('container.private'));
 
-        // Referenced as '@<class>' in process configurations
-        $alias = $container->getAlias($class);
-        self::assertSame($id, (string) $alias);
-        self::assertTrue($alias->isPublic());
+        // Former id, deprecated
+        $alias = $container->getAlias($deprecatedId);
+        self::assertSame($class, (string) $alias);
+        self::assertFalse($alias->isPublic());
+        self::assertTrue($alias->isDeprecated());
+        self::assertSame(
+            ['package' => 'cleverage/archive-process-bundle', 'version' => '2.3', 'message' => 'The "'.$deprecatedId.'" service alias is deprecated, use the "'.$code.'" task code or the class name of the task instead. It will be removed in 3.0.'],
+            $alias->getDeprecation($deprecatedId)
+        );
     }
 }