refactor: refactor to templated trait+interface

[keradus]

first commit is selling idea
(later commits are mess to apply the idea - very draft, half regexped)

I want to be able to benefit from phpstan analysis for configuration. now it's simply array<string, mixed>.

externalised:

• chore: RandomApiMigrationFixer - do not modify configuration property #8033
• docs: global_namespace_import - simplify allowed config types #8023
• docs: better ConfigurableFixer allowed types #8024
• docs: don't expose list as config type for dicts #8081
• chore: add missing type in method prototype #8088

[coveralls]

coverage: 96.219% (+0.1%) from 96.121%
when pulling 38ed71a on keradus:options_template
into c3af946 on PHP-CS-Fixer:master.

[Wirone]

I agree this is something really needed, I already approached it at some point. If this helps PHPStan and IDE to understand available configuration options, adds autosuggestion support and makes weird workarounds just to satisfy SA obsolete, then it's great, BUT only if we have fixer/script for regenerating _Configuration meta-type for each configurable fixer. I can't imagine defining/maintaining config options in 2 places manually. Also, what about config options that have a lot of acceptable values? Do we want to list them all, or use generic stuff like list<string>?

But I have a doubt - why trait was introduced? Do you want to take configuration part from AbstractFixer, because not every fixer is configurable, so the trait can be used only where ConfigurableFixerInterface is implemented? If yes, why not AbstractConfigurableFixer extends AbstractFixer? As I understand, we don't need to think about backward compatibility here since AbstractFixer is marked as @internal?

In general, this is rather achievable without the trait part:

• add @template TConfig of array<string, mixed> to AbstractFixer (along with template on ConfigurableFixerInterface?)
• change AbstractFixer::$configuration's phpDoc to @var null|TConfig and align related types accordingly
• each configurable fixer then need to do @extends AbstractFixer<{actual: 'shape'|'with'|'options'}>

But yeah, it does look weird when you need to define @extends and provide value for TConfig template even for fixers that are not configurable. I am wondering if it's possible to fallback to default value in such scenario 🤔.

[keradus]

I agree this is something really needed, phpstan/phpstan#9686 at some point.

indeed, that was my inspiration. [and I do not believe we need custom extension]

UT only if we have fixer/script for regenerating _Configuration meta-type

I like the idea. will see what i can craft

Also, what about config options that have a lot of acceptable values? Do we want to list them all, or use generic stuff like list?

likely sth generic only. better than nothing 🤷🏻
we have places when we allow subset of ['aaa', 'bbb', 'ccc', 'ddd', ...], or more complex structures. I would love to avoid overdoing it.

But I have a doubt - why trait was introduced?

making AbstractFixer a template class was complaining to me for non-configurable fixer to not specify template type, and making non-configurable fixer to declare extends AbstractFixer<void> was weird to me

[keradus]

the only mandatory config key in whole project

[jorismak]

This breaks certain custom-rules packages that work fine with 3.59.2. Like https://github.com/PedroTroller/PhpCSFixer-Custom-Fixers.

Is that a bug in the custom-rules package, or is this code more BC breaking than expected?

[keradus]

@jorismak ,
I discourage to use any of the INTERNAL class from Fixer's core repo in own repos, as they are NOT with BC promise.