#91 - Reference the tasks by a code in the process configurations

[njoubert-cleverage]

Description

Fixes #91: reference a task by a short code instead of its service, as the transformers (#276):

transform:
    task: transformer            # instead of service: '@CleverAge\ProcessBundle\Task\TransformerTask'
    options:
        transformers: { trim: ~ }

Changes

• Configuration: new task key, next to options. A task defines either task or service (A task must define either its code ("task: <code>") or, deprecated, its "service", not both). Named task rather than code: the task list uses useAttributeAsKey('code'), and Symfony re-keys any task containing a code attribute (even under a string YAML key) and removes it.
• service deprecated since 5.4, removed in v6.0 (setDeprecated() of the configuration node, so only for the tasks that set it, at container compilation, collected in the container deprecations log / profiler): The "service" option of the task "clever_age_process.configurations.<process>.tasks.<task>" is deprecated, reference the task by its code instead ("task: <code>", given on the reference page of each task; give a code to your own tasks with #[AsTask] or a "cleverage.task" tag). It will be removed in v6.0. It keeps working, with all its forms, until v6.0.
• Code of a task service: code attribute of a new cleverage.task tag, and new #[CleverAge\ProcessBundle\Attribute\AsTask(code: '...')] attribute (registerAttributeForAutoconfiguration()), as #[AsTransformer].
• Codes of the bundle tasks: the snake case of the class name without Task: transformer, constant_output, constant_iterable_output, csv_reader, csv_writer, input_iterator, file_writer, debug, stop… (a test checks that every bundle task has a unique code).
• Service ids: the tasks and transformers keep their class name as service id (config/services/task.yaml / transformer.yaml as defined explicitly by Apply Symfony best practices - Services #149). They stay public, but fetching them directly from the service container is deprecated since 5.4 (container.private tag, Symfony's mechanism: Accessing the "…" service directly from the container is deprecated, use dependency injection instead.); the references of the container, including the task and transformer locators, use the private service, without deprecation. They will be private in v6.0 (v6.0: remove the deprecated code #292). Autowiring by class and decoration keep working.
• Resolution at compile time (TaskLocatorCompilerPass, Fetch tasks from a service locator instead of the service container (v5 step of #114) #275): the task codes are replaced by the service of the tagged service (@<class>) in the configurations given to ProcessConfigurationRegistry — only the service key is set, on the raw configuration, so the parameters / escaped %% of the configurations are untouched — then the service goes in the task locator. An unknown code fails the container compilation, with the list of the known codes (Unknown task code "x" for the task "t" of the process "p". Known codes: "…"); duplicate or empty codes too.
• ProcessConfigurationRegistry: explicit LogicException for a task without service (a task code in a configuration added at runtime, which cannot be resolved).
• Docs: task definition reference (task required, service documented as deprecated), quick start (minimal syntax), custom tasks (new "Task code" section, #[AsTask], tag without autoconfiguration), the code (* **Code**: \transformer` (`task: transformer`)`) on the reference page of the 58 tasks and in the page template. All the examples use the codes: the 142 references to a task of the bundle by its service (67 files) were converted with the class → code table, the application task examples too.
• CHANGELOG (Latest): Reference the tasks by a code in the process configurations (task key, #[AsTask]) #91 and Apply Symfony best practices - Services #149 entries describe the final state.

To do before releasing 5.4 (else the users of the bridges get the deprecation without being able to use a code): give a code to the tasks of the bridge bundles (one issue per bridge), migrate the demo processes (400 service deprecations in its container build log), and #292 (v6.0: remove service, tasks and transformers private) is updated.

Checks

• Minimal compiled kernel: a process only defined with codes (constant_output → transformer → app_upper, an application task with #[AsTask]) gives the expected output, without deprecation; a process still using service works and gets the deprecation in the container deprecations log; $container->get(<class>) of a task / a transformer gets the container.private deprecation; an unknown code fails the boot with the list of the known codes.
• Demo project (all service; this change copied in vendor/, then reverted): lint:container OK, demo.transformer, demo.transformer_list, demo.file.csv_reader, demo.archive_zip executed.
• Tests: ConfigurationTest (task or service, neither / both rejected, deprecation of service only when set), TaskLocatorCompilerPassTest (codes resolved for bundle and application tasks, parameters untouched, unknown / duplicate / invalid code), CleverAgeProcessExtensionTest (unique code for every bundle task, #[AsTask]), ProcessConfigurationRegistryTest (unresolved code). 955 tests OK with code coverage (as the CI), PHPStan, PHP-CS-Fixer, Rector OK.

Requirements

• Documentation updates
  • Reference
  • Cookbooks
  • Changelog
• Unit tests

Breaking changes

None until v6.0: service keeps working (deprecated), the tasks and transformers stay public (direct access deprecated). Minor: service is no longer isRequired() in the configuration tree (the "neither task nor service" case is still rejected, with a new message), and config:dump-reference shows the new task key.

🤖 Generated with Claude Code