Another option is to add the basic DecoratedSuggestion and widen this argument type in Symfony 5.4 already, without immediately using its power.

I would widen it now, making it easier to write code support 5.4 and 6.1 by always providing the suggestion with description in the command

Note that your current plan also requires widening the getValueSuggestions return type, which is a BC break even on final classes.

@wouterj if you want to go for the widening type version, you need to tag getValueSuggestions as @internal so that we can change its return type to widen it (should be OK, as I don't think commands need to use it)

Widening a return type is not a BC break so we could do it later.

Widening a return type is not a BC break so we could do it later.

Are you sure? This means that you can never safely rely on the return type if you're the calling side of the code.

Widening a return type is not a BC break so we could do it later.

it definitely is a BC break for callers (which is also why child classes are not allow to widen a return type of their parent).

See btw also https://symfony.com/doc/current/contributing/code/bc.html#changing-classes :

It's a behavioral BC break if something unexpected is returned, but if there's an opt-in on the input side of the API, then it's fine.

so you would want to have getValueSuggestions($bcCastAsString = true) to make it backward compatible ?

We cannot rely on suggestValue() as being the opt-in for the return type of getValueSuggestions. Callers of the 2 methods can be in different places (the whole point of using that object is passing it around)

Oh: "Changing a return type is only possible with a child type.". As the proposed new suggestion class would be Stringable, I guess it's allowed.

The BC doc needs to tell about widening/narrowing :)

@wouterj Stringable is not a child type of string

So let's widen now indeed to be on the safe side.

I've proposed the alternative solution in a new PR: #44230

@nicolas-grekas widening a return type is a BC break all the time. Narrowing it is a BC break for child classes (requiring them to narrow their own return type in advance, which is the whole reason for tentative return types in PHP 8.1 core and our work in DebugClassLoader).

Let's close in favor of the new one, didn't see the conclusion before creating the other PR.