ProcessLauncherTask always fails: process_options normalizer returns an array despite its scalar return type

[njoubert-cleverage]

Description

ProcessLauncherTask cannot be used: every process using it fails as soon as the task is reached, whatever its configuration.

Reproduction

clever_age_process:
    configurations:
        demo.process_launcher:
            tasks:
                values:
                    service: '@CleverAge\ProcessBundle\Task\ConstantIterableOutputTask'
                    options:
                        output: [one, two, three]
                    outputs: [launch]
                launch:
                    service: '@CleverAge\ProcessBundle\Task\Process\ProcessLauncherTask'
                    options:
                        process: demo.process_launcher.child
                        max_processes: 2

        demo.process_launcher.child:
            public: false
            entry_point: log
            tasks:
                log:
                    service: '@CleverAge\ProcessBundle\Task\Reporting\LoggerTask'
                    options:
                        level: info
                        message: 'Child process received its input'

$ bin/console cleverage:process:execute demo.process_launcher
Starting process 'demo.process_launcher'...
CRITICAL [cleverage_process_task] CleverAge\ProcessBundle\Task\Process\ProcessLauncherTask::{closure:CleverAge\ProcessBundle\Task\Process\ProcessLauncherTask::configureOptions():223}(): Return value must be of type string|int|float|bool|null, array returned

In ProcessLauncherTask.php line 229:
  Process demo.process_launcher has failed during process launch with message: '...Return value must be of type string|int|float|bool|null, array returned'.

Tested on main (e70a620), PHP 8.5.8, Symfony 7.4.19.

Cause

In ProcessLauncherTask::configureOptions(), the normalizer of the deprecated process_options option declares a scalar return type, but returns the option value, which is always an array (setAllowedTypes('process_options', ['array']), default []):

$resolver->setNormalizer(
    'process_options',
    static function (Options $options, $value): int|float|string|bool|null {
        if (!empty($value)) {
            // Todo deprecation trigger
            throw new \InvalidArgumentException('Deprecated option, please contact support for help');
        }

        return $value; // always [] here => TypeError
    }
);

Normalizers also run on default values, so resolving the options always throws a TypeError. It is caught in ProcessManager::initialize() (logged as critical, task state stopped), and the process fails when the task is first executed.

The reference documentation added in #188 already describes the failure in the Notes section of docs/reference/tasks/process_launcher_task.md.

Proposed fix

• change the normalizer return type to array (checked locally: with this single change, the reproduction above runs until "Process 'demo.process_launcher' executed successfully");
• optionally, trigger a proper deprecation (trigger_deprecation()) instead of the // Todo deprecation trigger comment, or remove the deprecated option in the next major version;
• add a unit test resolving the task options with the default configuration;
• update the documentation:
  • docs/reference/tasks/process_launcher_task.md: remove the Known issue entry from the Notes section;
  • docs/04-advanced_workflow.md (Parallelization): remove ProcessLauncherTask from the warning (keep CommandRunnerTask until Fix CommandRunnerTask options handling #187 is merged);
  • docs/05-good_practices.md: remove the "currently broken by a known bug" mention.

Requirements

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

Breaking changes

None: every configuration of this task currently fails, so no working setup can break.