The migration path from cva to html_cva needs to be documented

[stof]

The changelog of TwigComponents mentions that cva is deprecated in favor of html_cva of twig/html-extra. The deprecation message also mentions this.

However, html_cva is not a drop-in replacement for which you can do a search-and-replace and be done with it. The signature of the function is different as html_cva has 4 (named) arguments instead of a single argument receiving an associative array with a shape with 4 keys.
the migration path between cva and html_cva needs to be documented clearly to avoid getting support requests from confused users complaining that things don't work anymore after they change function (which is already happening on Slack and triggered me to open this issue)

[smnandre]

Agree here. The change was presented as indolor but after some (legit) changes during Twig review process, the interfaces of the two functions differ a lot indeed.

@stof would you advise us to mimic/allow html_cva signature ? :|

I would naively think this should be the contrary, as we won't be able to follow Twig releases and changes, and have no "reason" to do so, but I'm sure it's more complex than that.. what do you think ?

[Kocal]

The cva() documentation and changelog already refer to https://twig.symfony.com/html_cva where there are several examples about html_cva() usages, and I thought that was enough for people to migrate.

Should we also write that html_cva() takes three parameters instead of one, and named arguments should be used instead?

[stof]

I think this migration from a single argument containing an associative array to named arguments should be mentioned explicitly in the upgrade documentation, yes (basically, you need to remove the { and } so that array keys become argument names instead, as the names are the same)