Audit qualité d'un site Drupal 8 / 9

Depuis que je travail avec Drupal j'ai pu contribuer à de nombreux projets, avec certains cas de reprises ou de maintenance.
L'un des problèmes constant est la piètre qualité des sites en reprise, aussi bien sur les petits projets que ceux gérés par de grosses entreprises, il semble y avoir une certaine constance dans un manque de gestion et contrôle technique.

La faute à Drupal ?

Drupal est très flexible et fourni de nombreux outils pour rapidement créer un site sur mesure. L'inconvénient est que cette flexibilité apporte beaucoup d'options pour faire les choses d'une mauvaise manière. Quand je dis "mauvaise" je quantifie ça objectivement par la difficulté de lire le code, la non utilisation de nombreuses fonctionnalités de site building, le difficulté d'évolution et de maintenance.

Avec Drupal 6 et 7 l'un des problèmes constant était l'utilisation de code PHP dans les templates, à l'époque PHP était utilisé directement pour le rendu. Les développeurs sans compétences de site building Drupal mettait toute la logique dans le thème, ce qui posait de nombreux problèmes.

Twig à la rescousse

L'intégration de Twig dans Drupal 8 promettait une solution à ce problème, plus possible d'insérer du code PHP dans les templates ! Mais les mauvaises pratiques ont la vie dure.
Pour utiliser du PHP dans les templates il reste le fichier .theme censé contenir un minimum de code, le plus utile étant les hook_theme_suggestions_HOOK_alter() pour permettre plus de flexibilité dans les templates et quelques hook_preprocess() pour ajouter certaines données manquantes dans les templates.
Mais malheureusement cette porte ouverte laisse de nouveau ceux qui ne savent pas utiliser le site building de Drupal polluer ce fichier de toute la logique du site...

Que des entreprises de taille raisonnable n'utilisent aucun outil d'audit de code est un problème de direction technique. Ou parfois d'argent, même si c'est un mauvais calcul.
Cependant pour les petites entreprises, embaucher un directeur technique n'est pas forcément possible. Heureusement il y a aujourd'hui de nombreux outils Open Source, simple à utiliser, qui permettent de rapidement se faire un avis sur la qualité du code d'un site Drupal, aussi bien en reprise qu'en création.
Il existe également de très bon produits payants mais ce n'est pas le sujet de cet article.

Outils d'audit PHP Drupal

Petite sélection de certains outils que j'utilise pour rapidement auditer un site.

L'incontournable PHP Code Sniffer pour vérifier l'utilisation des standard de code Drupal. Ce n'est pas suffisant pour évaluer la qualité du code mais c'est un bon départ. Cela, par exemple, facilite l'arrivée d'un autre développeur Drupal sur le projet, la lecture sera plus facile.
Et surtout cela permet d'avoir un premier aperçu de la rigueur utilisé pour le code custom.

PHPMD - PHP Mess Detector est un bon outil pour avoir un rapide aperçu de la qualité du code PHP.

PHP Copy/Paste Detector est un très bon outil de détection de partie du code redondante, créé par le talentueux Sebastian Bergmann, qui entre autre est derrière PHPunit.

Du même auteur, PhpLoc pour analyser la taille et la structure d'un projet.

PhpMetrics dans la même veine que Phploc pour déterminer la taille et évaluer les problèmes d'un projet.

Et enfin PHP Stan est un très puissant et flexible outil d'analyse du code qui permettra de détecter les problèmes rapidement. Sa configuration pour Drupal en fait un outil d'analyse indispensable à tous projets Drupal.

Il en existe bien sûr d'autres, ceci est une liste non exhaustive.

Installation rapide des outils sur un projet Drupal 8/9

Un autre projet permet de lancer plusieurs outils avec une seule commande, le très bon phpqa. Voici comment rapidement l'utiliser sur votre projet Drupal pour un rapide audit.

composer require edgedesign/phpqa drupal/coder dealerdirect/phpcodesniffer-composer-installer --dev

Il faudra ensuite un minimum de fichiers de configuration pour Drupal, à mettre à la racine de votre projet :

Fichier .phpqa.yml

# Default common config for Phpqa.
# @see https://github.com/EdgedesignCZ/phpqa/blob/master/.phpqa.yml
phpcs:
  standard:
    - Drupal
    # Drupal best practices, uncomment for perfect standard checking.
    # - DrupalPractice
  ignoreWarnings: true
  reports:
    cli:
      - full
    file:
      checkstyle: checkstyle.xml
phpmd:
  standard: .phpmd.xml
phpcpd:
  minLines: 5
  minTokens: 70
phpqa:
  ignoredDirs: "vendor,bootstrap,tests"
  ignoredFiles: "Readme.md,*Test.php"
  report: true
  verbose: true
  execution: parallel
  extensions:
    - php
    - inc
    - module
    - install
    - test
    - profile
    - theme

Le fichier de règle .phpmd.xml que vous pouvez trouver sur mon projet Gitlab.

Lancer et interpréter les résultats

Il suffit ensuite de lancer l'analyse phpqa pour obtenir un rapport html des résultats, depuis la racine de votre projet. Ici nous réglons pour aucune erreure de standard de code ou de copier coller de code :

vendor/bin/phpqa --tools=phpcs:0,phpcpd:0,phpmd,phploc,phpmetrics --analyzedDirs=./web/modules/custom,./web/themes/custom --buildDir ./build

Un répertoire ./build contient les rapports html du résultat.

Il suffit ensuite de naviguer sur les résultats. Sachez qu'il est probablement impossible de ne pas avoir la moindre erreure, masis si le nombre semble important, c'est qu'il y a un problème de qualité dans votre projet.

Pour phpcs il est possible simplement d'arriver simplement à aucune erreur. Un code qui respecte les standards n'est pas plus compliqué. De même pour phpcpd, il n'est pas normal d'avoir les mêmes portions de code à plusieurs endroits, c'est un petit peu un principe de base de la programmation : ne pas se répéter !
Pour phpmd c'est un peu plus délicat, il faut regarder plus précisément la nature des erreurs.
Phploc et phpmetrics vont donner une indication globale de qualité de façon plus ou moins explicite.

Le cas PHPStan

Pour l'instant il y a un PR en cours pour utiliser PHPstan avec Phpqa, donc nous l'utiliserons en stand alone. La première étape est donc de l'installer :

composer require mglaman/phpstan-drupal phpstan/phpstan-deprecation-rules phpstan/extension-installer --dev

Voici le fichier de configuration pour Drupal, à placer à la racine du projet avec le nom phpstan.neon :

parameters:
level: 1
excludePaths:
  analyseAndScan:
    - */tests/*
    - */Tests/*
inferPrivatePropertyTypeFromConstructor: true
checkMissingIterableValueType: false
## Ignore some errors.
reportUnmatchedIgnoredErrors: false
ignoreErrors:
  - '#Unsafe usage of new static\(\).#'

Le niveau 1 est assez bas, Phpstan vas de 0 à 9. Mais Drupal n'est pas encore parfait, une première passe niveau 1 permet d'avoir un bon aperçu de la qualité, si le code passe le niveau 3, alors c'est un code de qualité.
L'analyse niveau 3 est un bon niveau pour du code custom Drupal, et permet d'évaluer rapidement la qualité du code.

Lancer l'analyse par PHPStan :

vendor/bin/phpstan analyse web/modules/custom/ web/themes/custom/

Détection du code déprécié

Dans le cas d'un suivi du projet et d'une mise à jour vers une nouvelle version de Drupal, il est très utile de détecter assez tôt le code obsolète qui doit être adapté. Pour ça PhpStan va nous aider avec la détection de ce code.

composer require phpstan/phpstan-deprecation-rules --dev

En lançant de nouveau l'analyse de notre code, les erreurs de ce type vont être détectés dans le rapport.

Conclusion

Cette première étape permet d'avoir un aperçu rapide et non subjectif. Bien sûr cela ne prends pas en compte le site building de Drupal qui peut parfois s'avérer problématique, mais c'est un bon début et un moyen très efficace d'avoir un avis objectif et quantifié sur la qualité de votre projet.

La seconde étape sera d'intégrer directement ces outils dans votre intégration continue pour s'assurer de la qualité du projet durant tout son cycle de vie.

Vous trouverez un exemple avec mon integration de Drupal avec Gitlab ci.