Analyse statique dans un PHP legacy : plan de modernisation sûr

Introduire l’analyse statique dans un PHP legacy ne consiste pas à activer le niveau le plus strict d’un outil et à corriger des milliers d’avertissements. Dans une application où les règles métier sont dispersées, les dépendances anciennes et les tests peu nombreux, cette approche mélange des défauts potentiellement graves et de la dette historique, ralentit l’équipe et peut entraîner des changements risqués.

L’objectif initial est différent : rendre chaque nouvelle modification plus vérifiable, réduire l’incertitude dans les flux importants et disposer d’une voie explicite pour traiter la dette existante. L’analyse statique apporte des informations structurelles sur le code ; la modernisation exige également des décisions produit, des tests et des contrôles de livraison.

Pourquoi activer toutes les règles d’un coup paralyse souvent la maintenance

Un projet legacy peut accumuler des types implicites, des valeurs nulles non documentées, des méthodes avec trop de responsabilités, un accès direct aux variables globales, du code inatteignable et des contrats ambigus entre les couches. Si l’ensemble du dépôt est analysé avec des règles strictes dès le premier jour, le résultat est généralement une liste trop longue pour être priorisée.

Le problème n’est pas seulement le volume. Chaque avertissement exige du contexte : un appel apparemment incorrect peut être protégé par une condition externe, une dépendance peut utiliser des annotations incomplètes ou une convention locale peut ne pas être représentée dans le code. Corriger sans comprendre ce contexte peut modifier un comportement métier que personne n’avait documenté.

Il convient également de séparer deux objectifs souvent confondus :

• Visibilité : connaître les risques et les zones aux contrats incertains.
• Contrôle des changements : empêcher qu’une modification introduise de nouveaux problèmes détectables.
• Réduction de la dette : éliminer les anomalies historiques de manière priorisée.

Le deuxième objectif est le meilleur point de départ. Il permet d’améliorer la qualité de livraison sans faire de la correction massive un prérequis pour continuer à développer le produit.

Ce que détecte l’analyse statique et les contrôles qu’elle ne remplace pas

Un analyseur peut inférer les types, suivre les appels, détecter des arguments incompatibles, des valeurs de retour impossibles, des propriétés non définies, des variables pouvant être nulles, des branches inatteignables et des divergences entre une interface et son implémentation. Il aide également à localiser des dépendances couplées, des API utilisées de manière incohérente et des limites d’architecture violées lorsque des règles sont définies à cet effet.

Ces signaux sont particulièrement précieux lors des refactorisations. Par exemple, modifier une méthode pour qu’elle retourne Customer|null permet de trouver les consommateurs qui supposent systématiquement une instance. L’avertissement ne démontre pas qu’une erreur existe en production, mais il oblige à décider ce qui doit se passer lorsqu’il n’y a pas de client.

Cependant, l’analyse ne valide pas à elle seule une règle telle qu’une commande ne puisse être annulée qu’avant sa facturation, qu’une remise soit calculée conformément à une politique commerciale ou qu’une intégration externe réponde dans un délai acceptable. Elle n’observe pas non plus les autorisations effectives, les migrations de données, la concurrence, les performances ni les configurations de production.

Une refactorisation sûre combine trois perspectives :

• Analyse statique pour vérifier les contrats et les parcours de code.
• Tests automatisés pour préserver les comportements connus, en commençant par les flux critiques.
• Revue fonctionnelle et observation pour valider les règles métier, les effets externes et le comportement après le déploiement.

Préparer le pilote avant de mesurer les anomalies

Le premier périmètre doit être un module métier circonscrit, avec des changements fréquents ou un risque pertinent, mais pas le noyau le plus opaque de toute l’application. Un pilote utile a des responsables identifiables et permet de savoir si les règles génèrent des signalements compréhensibles.

Avant d’exécuter l’analyse, établissez un inventaire bref :

1. Parcours critiques : authentification, paiements, commandes, facturation, données personnelles ou autres opérations dont l’échec a un impact élevé.
2. Entrées et sorties : contrôleurs, commandes, consommateurs de files d’attente, API, fichiers importés et tâches planifiées.
3. Dépendances : version de PHP, paquets abandonnés, extensions, code généré et bibliothèques sans informations de type.
4. Conventions actuelles : utilisation de classes de valeur, d’exceptions, de collections, de valeurs nulles, de tableaux associatifs et d’accès aux données.
5. Tests disponibles : quels scénarios ils couvrent, quelles données ils préparent et quelles sont leurs limites de confiance.

Cet inventaire évite d’interpréter chaque avertissement isolément. Il permet également de décider où il est pertinent d’ajouter des types natifs et où il vaut mieux conserver des adaptateurs autour d’une dépendance ancienne afin de ne pas propager son ambiguïté dans toute l’application.

Créer une ligne de base sans en faire une amnistie permanente

La ligne de base enregistre les anomalies déjà existantes afin que l’équipe puisse exiger un standard plus élevé dans le code nouveau ou modifié. C’est un outil de transition, pas une déclaration selon laquelle la dette est acceptable.

Générez-la après avoir examiné un échantillon représentatif des constats. Si le résultat contient des erreurs de configuration, des chemins qui ne devraient pas être analysés ou du code tiers inclus par accident, corrigez-les d’abord. Une ligne de base gonflée par du bruit perd de sa valeur dès le départ.

Pour qu’elle soit utile, associez-la à des règles opérationnelles :

• Aucune nouvelle entrée n’est ajoutée à la ligne de base sans justification révisable.
• Une anomalie corrigée est supprimée de la ligne de base dans le même changement.
• Les entrées sont examinées lors d’une intervention sur le fichier ou le module concerné.
• Les exceptions ont un propriétaire, un motif technique et une date ou une condition de révision.

Il est préférable d’enregistrer une suppression très localisée avec une explication plutôt que de masquer toute une catégorie d’erreurs. Si un avertissement ne peut pas être résolu parce qu’une bibliothèque externe n’exprime pas ses contrats, encapsulez cette bibliothèque dans un adaptateur typé et limitez l’exception à cette frontière.

Classer les constats selon le risque et le coût de décision

Tous les diagnostics ne méritent pas de bloquer une livraison. La classification doit refléter l’impact potentiel et le degré de certitude, et pas seulement la sévérité attribuée par un outil.

Priorité élevée : contrats et données critiques

Traitez d’abord les valeurs de retour incompatibles, les arguments mal typés dans les opérations métier, les accès possibles à des valeurs nulles, les valeurs non validées aux frontières externes et les violations de contrats entre modules. Ils révèlent souvent des défauts qu’un test insuffisant peut ne pas parcourir.

Priorité moyenne : incertitude qui élargit le périmètre

Les tableaux sans forme connue, les valeurs mixtes qui traversent plusieurs couches et les méthodes qui retournent des types trop larges ne provoquent pas toujours une défaillance immédiate. Ils augmentent néanmoins le coût de chaque changement. Il est préférable de les résoudre lors de la modification du flux, en définissant des objets de transfert, des classes de valeur ou des contrats explicites lorsque cela a du sens.

Priorité faible : nettoyage sans impact démontré

Le style, le code redondant ou les conventions internes peuvent améliorer la lisibilité, mais ils ne devraient pas concurrencer les risques métier ni les livraisons urgentes. Regroupez-les dans des tâches séparées ou appliquez des règles automatiques uniquement lorsque leur modification est mécanique et vérifiable.

Ordre d’intervention : empêcher toute nouvelle dette et protéger les flux actifs

Une séquence pratique commence par exécuter l’analyse dans l’intégration continue sur les modifications proposées. Le critère de blocage initial peut être simple : ne pas introduire de nouvelles erreurs hors de la ligne de base et ne pas dégrader le niveau d’un fichier modifié.

Ensuite, durcissez les règles par répertoire ou par module. Il est courant de commencer par le nouveau code métier, les services d’application et les adaptateurs récents, tout en maintenant des critères plus tolérants dans les couches historiques d’infrastructure. Cette division n’est pas une excuse pour abandonner le legacy : elle rend visible où se trouve la limite et permet de la déplacer progressivement.

Dans chaque changement actif, privilégiez un périmètre réduit :

1. Ajoutez des tests de caractérisation pour le comportement que vous devez préserver.
2. Déclarez le contrat d’entrée et de sortie le plus pertinent.
3. Corrigez les avertissements qui affectent ce parcours.
4. Refactorisez par étapes courtes et examinez les différences fonctionnelles.
5. Activez des règles plus strictes lorsque le module peut les supporter.

Les types et annotations doivent décrire une connaissance réelle. Déclarer un type non nul uniquement pour faire taire un avertissement transfère le risque au consommateur suivant. Si une valeur peut manquer par conception, représentez-la comme telle et obligez le code appelant à décider comment la gérer.

Intégrer les contrôles dans la livraison continue sans bloquer à cause du bruit

Le résultat de l’analyse doit être lisible pour la personne qui ouvre un changement. Publiez les nouvelles erreurs, le fichier concerné, la règle et une indication de leur importance. Évitez les rapports longs sans responsable ni lien avec la modification effectuée.

Définissez des critères proportionnés : les défauts de contrat dans un flux critique peuvent bloquer ; une amélioration cosmétique peut devenir un suivi ; une alerte incertaine liée à une dépendance doit conduire à un adaptateur, une configuration documentée ou une exception temporaire. La revue de code décide si la correction respecte l’intention métier ; l’analyseur ne remplace pas cette décision.

Mesurez l’avancement avec des indicateurs qui orientent les décisions : anomalies pertinentes ouvertes par module, entrées de ligne de base supprimées, pourcentage de changements analysés avec des règles exigeantes, nombre de contrats ambigus dans les parcours critiques et proportion de refactorisations couvertes par des tests de caractérisation. L’objectif n’est pas d’atteindre zéro avertissement global, mais de réduire le périmètre incertain des changements.

Antipatterns qui confondent nettoyage et modernisation

• Supprimer des avertissements sans motif : cela élimine des informations sans réduire le risque qui les a générées.
• Viser zéro signalement : cela peut consacrer de la capacité à des détails non pertinents alors que les processus importants restent à risque.
• Corriger tout fichier proche : cela augmente la taille du changement et complique l’examen des régressions.
• Typer des données inconnues comme si elles étaient fiables : cela masque l’incertitude au lieu de la modéliser.
• Bloquer toute livraison avec de nouvelles règles : cela génère du rejet et pousse l’équipe à rechercher des exceptions permanentes.

Liste de vérification pour démarrer le pilote

• Choisir un module avec un responsable technique, une pertinence métier et un périmètre circonscrit.
• Identifier ses entrées, ses sorties, ses dépendances et ses scénarios critiques.
• Exécuter l’analyse, éliminer les erreurs de configuration et examiner un échantillon des constats.
• Créer une ligne de base limitée à la dette existante et définir qui peut la modifier.
• Bloquer les nouvelles anomalies à haut risque dans les changements du pilote.
• Ajouter des tests de caractérisation avant de refactoriser des parcours sensibles.
• Examiner chaque semaine les alertes répétées, les exceptions et les règles qui génèrent du bruit.
• Durcir le standard uniquement lorsque les constats sont compréhensibles et exploitables.

Avec cette approche, l’analyse statique cesse d’être un rapport sur des défauts hérités et devient un mécanisme de contrôle : chaque modification apporte des contrats plus clairs, moins d’incertitude et une base plus sûre pour moderniser PHP progressivement.