Mesurer la qualité de votre code PHP en 5 métriques clés

Tu as l'impression que ton code PHP est "correct" mais tu n'as aucun chiffre pour le prouver ? La qualité du code ne se résume pas à "ça marche en prod". Sans métriques objectives, la dette technique s'accumule silencieusement jusqu'au jour où chaque modification devient un cauchemar. Voici les 5 métriques clés que tout projet PHP devrait surveiller — et les seuils à viser.

1. Complexité cyclomatique : la lisibilité de tes méthodes

La complexité cyclomatique (CC) mesure le nombre de chemins d'exécution dans une méthode. Chaque if, foreach, switch/case ou catch ajoute un chemin. Plus la CC est élevée, plus la méthode est difficile à comprendre, tester et maintenir.

• Excellent : CC < 4 par méthode — code linéaire et lisible
• Bon : CC entre 4 et 7 — logique conditionnelle raisonnable
• Moyen : CC entre 7 et 12 — refactoring recommandé
• Mauvais : CC > 12 — God method à découper d'urgence

Cible : CC < 10 par méthode. Au-delà, découpe la méthode en sous-méthodes avec des noms explicites. L'outil de référence est PHPMD (PHP Mess Detector), qui détecte aussi les God classes et le code mort.

# Installer et lancer PHPMD
composer require --dev phpmd/phpmd
vendor/bin/phpmd src/ text codesize,unusedcode,naming

2. Niveau PHPStan : la rigueur du typage

PHPStan est l'analyseur statique de référence en PHP. Il fonctionne par niveaux (0 à 9), chaque niveau ajoutant des vérifications plus strictes. Le niveau 0 détecte les erreurs évidentes (classes inexistantes, mauvais nombre d'arguments). Le niveau 9 impose un typage complet avec des génériques.

• Niveau 0-4 : détection d'erreurs basiques — le strict minimum
• Niveau 5-6 : vérification des types de retour et des arguments
• Niveau 7-8 : unions de types, null safety, types stricts
• Niveau 9 : typage complet incluant les génériques et les templates

Cible : niveau 9. Si tu pars de zéro, monte d'un niveau par sprint. Chaque niveau supplémentaire détecte des bugs que les tests manuels ratent. Mesure le nombre d'erreurs par fichier : en dessous de 0.5 erreur/fichier, tu es dans le vert.

# Installer et lancer PHPStan au niveau 9
composer require --dev phpstan/phpstan
vendor/bin/phpstan analyse src/ --level=9

3. Taux de duplication : le copier-coller invisible

Le code dupliqué est un multiplicateur de dette. Chaque bug dans un bloc copié-collé doit être corrigé autant de fois qu'il existe de copies. PHPCPD (PHP Copy/Paste Detector) analyse la codebase par tokens et détecte les blocs identiques ou quasi-identiques.

• Excellent : < 3% de duplication
• Bon : entre 3% et 8%
• Moyen : entre 8% et 15%
• Mauvais : > 15% — refactoring urgent vers des abstractions

Cible : < 3%. Chaque bloc dupliqué détecté est une opportunité d'extraction vers un service, un trait ou une méthode privée. Le coût de correction est faible, le gain en maintenabilité est considérable.

# Détecter les duplications (seuil 70 tokens)
composer require --dev sebastian/phpcpd
vendor/bin/phpcpd src/ --min-tokens=70

4. LCOM : la cohésion de tes classes

LCOM (Lack of Cohesion of Methods) mesure à quel point les méthodes d'une classe utilisent les mêmes propriétés. Un LCOM élevé signifie que ta classe fait trop de choses — c'est probablement une God class déguisée qui devrait être découpée en plusieurs classes spécialisées.

• Excellent : LCOM < 1.5 — classe cohérente avec une responsabilité claire
• Bon : LCOM entre 1.5 et 3
• Moyen : LCOM entre 3 et 5 — la classe fait probablement trop de choses
• Mauvais : LCOM > 5 — God class à refactorer

Cible : LCOM < 2. L'outil PhpMetrics calcule le LCOM automatiquement et génère un rapport HTML navigable avec une cartographie visuelle de toutes tes classes.

# Générer un rapport complet avec PhpMetrics
composer require --dev phpmetrics/phpmetrics
vendor/bin/phpmetrics --report-html=report/ src/

5. Couplage afférent/efférent : la fragilité architecturale

Le couplage afférent (Ca) mesure combien de classes dépendent de ta classe. Le couplage efférent (Ce) mesure combien de classes ta classe utilise. Un Ca élevé signifie que ta classe est critique : si tu la modifies, beaucoup de code sera impacté. Un Ce élevé signifie que ta classe a trop de dépendances et sera fragile face aux changements.

• Couplage afférent (Ca) : cible < 8 en moyenne — au-delà, la classe est un point de fragilité
• Couplage efférent (Ce) : cible < 8 — au-delà, la classe a trop de dépendances
• Instabilité (I = Ce / (Ca + Ce)) : 0 = stable (classe abstraite), 1 = instable (classe concrète)

PhpMetrics et Deptrac sont les deux outils complémentaires pour surveiller le couplage. PhpMetrics donne les chiffres, Deptrac vérifie que les règles architecturales (ex : le Domain ne dépend pas de l'Infrastructure) sont respectées.

Automatiser la mesure : un tableau de bord en une commande

Mesurer ponctuellement ne suffit pas. Intègre ces outils dans ta CI pour suivre l'évolution dans le temps. Voici un exemple de pipeline minimal qui couvre les 5 métriques :

# .github/workflows/quality.yml
name: Quality Gate
on: [push, pull_request]
jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with: { php-version: 8.3 }
      - run: composer install --no-progress
      - run: vendor/bin/phpstan analyse src/ --level=9 --no-progress
      - run: vendor/bin/phpmd src/ text codesize
      - run: vendor/bin/phpcpd src/
      - run: vendor/bin/phpmetrics --report-json=metrics.json src/

Aller plus loin avec un audit complet

Ces 5 métriques constituent le socle minimum. Un audit complet couvre également la sécurité (OWASP Top 10, CVE des dépendances), la testabilité (couverture, ratio tests/classes), la performance (N+1 Doctrine, SELECT *) et la maintenabilité (versions obsolètes, dépréciations). Bear Scan automatise l'ensemble : score A-F, roadmap priorisée par ROI, et chiffrage des actions correctives. Si tu veux un état des lieux objectif et actionnable de ta codebase PHP, réserve un appel découverte — le diagnostic commence par les chiffres.