PHP CS Fixer : le formateur de notre code PHP

Le fichier est copié dans chaque projet par la recette Symfony Flex du standard-bundle. Il tient en deux parties : le périmètre, et les règles.

$finder = (new PhpCsFixer\Finder())
    ->in(__DIR__)
    ->exclude('var')
    ->exclude('vendor')
    ->exclude('node_modules')
    ->append([
        'bin/console',
    ])
    ->path([
        'bin/',
        'config/',
        'public/',
        'src/',
        'tests/',
    ])
;

return (new PhpCsFixer\Config())
    ->setRiskyAllowed(true)
    ->setRules([
        '@Symfony' => true,
        'class_definition' => [
            'multi_line_extends_each_single_line' => true, # https://cs.symfony.com/doc/rules/class_notation/class_definition.html#example-4
        ],
        'concat_space' => ['spacing' => 'one'], # the @PER like PSR12 preserve space
    ])
    ->setFinder($finder)
;

• ->path([...]) : seuls les répertoires listés sont formatés. bin/console est ajouté explicitement parce qu'il n'a pas d'extension .php.
• setRiskyAllowed(true) : autorise les règles qui peuvent changer le comportement du code. PHPStan et les tests, dans la même chaîne, servent de filet.
• @Symfony : le ruleset du framework, qui inclut PER Coding Style et donc PSR-12.
• class_definition : une classe qui implémente plusieurs interfaces les écrit une par ligne, ce qui rend les diffs lisibles quand on en ajoute une.
• concat_space : un espace autour du . de concaténation, comme PER le prévoit. Sans cette ligne, @Symfony les retire.

Toute règle ajoutée ici doit porter son motif en commentaire, sur la même ligne. Une règle sans motif est retirée à la revue.

Commande	Ce qu'elle fait	Quand
make cs	php-cs-fixer check -v : liste les fichiers non conformes, ne modifie rien	Avant de pousser, et en CI via make qa
make cs-diff	Même chose avec le diff de ce qui serait corrigé	Pour comprendre une violation
make cs-fix	php-cs-fixer fix -v --diff : corrige les fichiers	En local, avant de commiter
make cs-report	Écrit un rapport JSON des violations	Pour compter les règles en défaut sur un projet existant

Le rapport de make cs-report se lit avec jq, hors du conteneur, pour obtenir le nombre de violations par règle :

cat php_cs_fixer_report.json | jq -r '.files[] | select(.appliedFixers != null) | .appliedFixers[]' | sort | uniq -c | sort -nr

C'est la liste de départ de la migration règle par règle.

Un projet qui n'a jamais eu de formateur remonte des milliers de violations. Les corriger d'un coup produit un commit qui touche tous les fichiers, rend git blame inutilisable et bloque toutes les branches ouvertes. Nous procédons autrement.

1. Rendre la CI verte le jour même

Lancer make cs-report, lister les règles en défaut, et passer chacune à false dans .php-cs-fixer.dist.php :

->setRules([
    '@Symfony' => true,
    'phpdoc_tag_type' => false,
    'phpdoc_indent' => false,
    'single_quote' => false,
    // ...
])

Le ruleset est complet, les règles qui échouent sont suspendues, la chaîne de qualimétrie passe. Tout code nouveau est déjà contrôlé par les règles restées actives.

2. Réactiver les règles une par une

Retirer une ligne => false, lancer make cs-fix, relire le diff, commiter. Une règle par commit, avec le nom de la règle dans le message. Commencer par celles qui touchent peu de fichiers : le rapport de l'étape 1 donne l'ordre.

Chaque commit est relisible en revue, et l'historique dit exactement quand chaque convention est entrée en vigueur.

3. Dans le flux de la maintenance technique

Cette résorption n'est pas un chantier à part : elle entre dans le flux non prioritaire de la maintenance technique, le travail mené en autonomie entre deux demandes. Une session prend quelques règles, les réactive, et le projet rejoint progressivement le ruleset complet sans jamais bloquer une livraison.

Le même principe s'applique à la baseline de PHPStan et à celle de Psalm : voir la page conventions de code.