Allowing multiple valued @options via 'new' annotation method?

[JacobSanford]

consolidation/annotated-command: 4.5.2 
consolidation/robo: 3.0.10
PHP 8.1.2

I am unsure if this issue belongs here, or in the consolidation/robo repository. Apologies if I have chosen incorrectly.

Following the 'legacy' hint in the documentation, we are attempting to migrate our @commands in Robo from the 'Legacy Annotated Command Methods' to the current method.

We are struggling with how to port @option items that allow multiple values. Legacy method:

/**
[...]
   * @option branch
   *   The branch to restart the build in. Defaults to 'dev'.
[...]
**/
public function doSomething(array $options = [
      'branch' => ['dev'],
    ]
) {

This allowed the user to specify as many branches as desired (while also defining a default option) via multiple switches. It also added '(multiple values allowed)' to the --help text.

One initial effort to port this was to 'type' the function argument in the method signature as array:

/**
[...]
   * @param array $branch
   *   The 'branch' option.
   * @option branch
   *   The branch to restart the build in. Defaults to 'dev'.
[...]
**/
public function doSomething(array $branch = ['dev']) {

this only resulted in a type validation error, as the framework passes a non-array.

How should this desired behavior be defined using the new annotation method? Is it possible, or In the 'new' method are multiple valued options only achievable using separators (--branch=dev,prod) and manual parsing (e.g. explode) within the command?

Warm regards, and many thanks for your efforts.

[greg-1-anderson]

Your second example should work, or I should say your second example is intended to work. Try with one argument; I believe there may be a bug with zero-argument commands that have options. I haven't had a chance to isolate and fix yet.

[greg-1-anderson]

I did some brief tests and could only get binary / valueless options to work. This is a bug.

[JacobSanford]

Hi Greg,

Thanks for the investigation and time. Would you prefer I open a new, more targeted issue addressing this?

[Sweetchuck]

It is not a good idea to have an argument and an option with the same name.

[greg-1-anderson]

@param is for php; @option is for Robo / Annotated Commands. Sorry if this is confusing; some folks / linters prefer to strictly have one @param for every PHP method parameter. If you're using PHP 8+, then you may use PHP annotations instead of @option, in which case the @param isn't quite as confusing.

I don't recall if this bug has been fixed; I did some work on options in the Annotated Command library some time back. It would be better to track issues with that library in its own queue.