PHP CS Fixer x PHPStan : attention au traitement des DocBlocks !

31 mars 2022 à 03:42

Récemment, je suis tombé sur ce cas : https://phpstan.org/r/b8849240-30d4-4001-9d69-d0a071addb5b

Je ne vais pas décrire le code, je pense que vous comprenez l'implémentation. En soi, c'est valide (cf. le commentaire sur la méthode "FooRepository::baz") mais PHPStan ne le comprend pas sans aide.

Aucun problème, aidons PHPStan : https://phpstan.org/r/3092e11e-dc78-4f65-ab0b-94ea682540c2 (utilisation des Generics).

Plus d'erreur, super ! Pourtant, le job "Quality" de la CI continue de fail... 😢

Avant de commit mon code, je lance PHP CS Fixer (dans ce projet, il y a simplement la règle "@Symfony" d'utilisée).

Ce que j'ignorais, c'est que par défaut, PHP CS Fixer va convertir tous les DocBlocks qui ne contiennent pas de la PHPDoc en commentaire "standard".

Donc ceci : 

/** // <- 2 astérisques = DocBlock
 * @phpstan-use FooTrait<FooEntity>
 */
use FooTrait;

est transformé en :

/* // <- Plus qu'un seul astérisque ici !
 * @phpstan-use FooTrait<FooEntity>
 */
use FooTrait;

Par conséquent, PHPStan ne prend plus en compte l'annotation : https://phpstan.org/r/56445228-13b6-44e7-afd8-8ebdc7016b28

Pour éviter ce problème, il faut :

Sur PHP CS Fixer v2 :

Activer l'option phpdoc_to_comment

->setRules([
    '@Symfony' => true,
    'phpdoc_to_comment' => false,
])

https://github.com/FriendsOfPHP/PHP-CS-Fixer/blob/2.19/doc/rules/phpdoc/phpdoc_to_comment.rst

Sur PHP CS Fixer v3 : 

La version 3 n'attend pas un booléen mais un tableau, car on peut configurer le traitement par bloc.

Dans mon exemple, ce serait bien de seulement désactiver la transformation sur les "use" et garder le comportement par défaut sur le reste des blocks. 

Avec la version 3, c'est possible ! 

->setRules([
    '@Symfony' => true,
    'phpdoc_to_comment' => ['ignored_tags' => ['use']],
])