Another option is to add the basicDecoratedSuggestion 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 thegetValueSuggestions 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 taggetValueSuggestions 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 alsohttps://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 havegetValueSuggestions($bcCastAsString = true) to make it backward compatible ?

We cannot rely onsuggestValue() as being the opt-in for the return type ofgetValueSuggestions. 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 beStringable, I guess it's allowed.

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

@wouterjStringable is not a child type ofstring

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.