Déboguer un projet PHP avec XDebug

XDebug est un outil puissant pour le débogage, le profilage et l’analyse de couverture de code en développement PHP. L'intégration et l’utilisation de XDebug dans l’environnement de développement local ServBay permettent d'améliorer notablement la productivité et la qualité des projets PHP. Grâce à XDebug, vous pouvez poser des points d’arrêt dans votre code, inspecter les valeurs des variables, suivre la pile d’appels des fonctions, analyser les goulets d’étranglement de performance, etc. pour identifier et résoudre les problèmes plus efficacement.

Présentation de XDebug

XDebug est une extension conçue pour PHP, offrant des fonctionnalités avancées de débogage et d’analyse. Elle prend en charge le débogage à distance (généralement via le protocole DBGp), la pose de points d’arrêt, l’exécution pas à pas, l’inspection des valeurs de variables, la traçabilité des appels de fonctions, l’analyse des performances de scripts (Profiling) et la génération de rapports de couverture du code (Coverage). Avec XDebug, les développeurs peuvent comprendre en profondeur le flux d’exécution et l’état de leur application, leur permettant ainsi de localiser et résoudre les problèmes plus rapidement.

XDebug offre différents modes de fonctionnement, le mode le plus utilisé étant le mode debug pour le débogage interactif à points d’arrêt.

Activer et configurer XDebug dans ServBay

ServBay intègre d’office l’extension XDebug pour chaque version de PHP prise en charge. Aucun téléchargement ou compilation manuelle n’est nécessaire.

1. Activer le module XDebug : Ouvrez l’interface de l’application ServBay. Naviguez jusqu’à Langages > PHP et sélectionnez la version PHP pour laquelle vous souhaitez activer XDebug. Dans la section Extensions, repérez le module xdebug et assurez-vous qu’il est bien activé. Si ce n’est pas le cas, cliquez sur « Activer ». Un redémarrage du service PHP-FPM peut être nécessaire (ServBay l’effectue généralement automatiquement).

2. Configurer votre IDE : Dans votre Environnement de Développement Intégré (IDE) de prédilection, tel que PHPStorm ou VS Code, configurez la connexion à XDebug. Cela consiste habituellement à définir le port d’écoute (qui doit correspondre aux réglages de l’interface ServBay pour XDebug) ainsi que, si nécessaire, à mettre en place un mapping des chemins distants (cependant, dans l’environnement local de ServBay, cela n’est généralement pas requis).

   Plus de détails sur la configuration IDE

   Pour des instructions détaillées concernant la configuration de XDebug dans des IDE spécifiques (comme PHPStorm, VS Code, etc.), veuillez consulter la documentation de votre IDE ou l’article Comment activer le module Xdebug natif de ServBay.

Exemple pratique : déboguer un projet PHP dans ServBay

Voici un exemple concret pour illustrer l’utilisation de XDebug dans ServBay.

1. Créer un site ServBay

Commencez par créer un nouveau site dans ServBay pour héberger notre projet exemple :

1. Dans le répertoire racine des sites de ServBay /Applications/ServBay/www/, créez un dossier de projet, par exemple servbay-xdebug-app.
2. Ouvrez l’interface ServBay, puis dirigez-vous vers la section « Sites ».
3. Cliquez sur « Ajouter un site » et indiquez comme racine /Applications/ServBay/www/servbay-xdebug-app.
4. Attribuez un domaine local, par exemple servbay-xdebug-app.servbay.demo.
5. Sélectionnez la version de PHP souhaitée et assurez-vous que XDebug est bien activé et configuré conformément aux étapes précédentes.
6. Enregistrez et appliquez les modifications. ServBay se chargera automatiquement de la configuration de Caddy/Nginx et de la mise à jour du fichier hosts (ou utilisera son service DNS).

2. Structure et code du projet exemple

Dans le dossier /Applications/ServBay/www/servbay-xdebug-app/, créez la structure suivante :

servbay-xdebug-app/
├── src/
│   └── Calculator.php
└── index.php

Le fichier src/Calculator.php :

<?php
namespace App;

class Calculator
{
    public function add($a, $b)
    {
        // Posez ici un point d’arrêt
        return $a + $b;
    }

    public function subtract($a, $b)
    {
        return $a - $b;
    }
}

Le fichier index.php :

<?php
// Supposons que vous utilisez Composer, l’autoloader est chargé ici
// Si vous n’utilisez pas Composer, adaptez l’inclusion en conséquence
require __DIR__ . '/vendor/autoload.php';

use App\Calculator;

echo "Debugging Example:\n";

$calculator = new Calculator();
$num1 = 5;
$num2 = 3;

$sum = $calculator->add($num1, $num2);
$difference = $calculator->subtract($num1, $num2);

echo "Sum: " . $sum . "\n";
echo "Difference: " . $difference . "\n";

echo "Done.\n";
?>

Remarque : L’instruction require __DIR__ . '/vendor/autoload.php'; suppose l’utilisation de Composer. Si vous faites un simple test, vous pouvez supprimer cette ligne et remplacer use App\Calculator; par require __DIR__ . '/src/Calculator.php';.

3. Posez un point d’arrêt

Dans votre IDE (par exemple PHPStorm), ouvrez le fichier /Applications/ServBay/www/servbay-xdebug-app/src/Calculator.php. Cliquez à côté de la ligne return $a + $b; dans la méthode add pour poser un point d’arrêt.

4. Démarrez une session de débogage

1. Dans votre IDE, activez l’écoute des connexions XDebug. Dans PHPStorm, il suffit généralement de cliquer sur « Start Listening for PHP Debug Connections » (un combiné téléphonique ou une petite icône de bug en haut).
2. Accédez à la page index.php de votre site ServBay dans un navigateur : https://servbay-xdebug-app.servbay.demo/index.php.
3. Si l’option xdebug.start_with_request est définie sur trigger, veillez à utiliser une extension de navigateur ou à ajouter manuellement un déclencheur XDebug (par exemple : https://servbay-xdebug-app.servbay.demo/index.php?XDEBUG_TRIGGER=1).

5. Procédure de débogage

1. Lorsque votre navigateur accède à index.php et déclenche une session XDebug, l’extension se connecte alors à votre IDE et interrompt l’exécution au point d’arrêt défini.
2. L’IDE affiche la vue de débogage, où le code est figé sur la ligne du point d’arrêt, dans la méthode add du fichier Calculator.php.

6. Inspection des variables

1. Dans le panneau de débogage de votre IDE, vous pouvez consulter la ligne courante, la pile d'appels (« Call Stack »), la valeur des variables, etc.
2. Dans l’onglet « Variables », vous pouvez voir la valeur des variables en cours : $a contient 5, $b contient 3, par exemple.

7. Exécution pas à pas

1. Utilisez les boutons de contrôle du débogueur (généralement : Step Over (F8), Step Into (F7), Step Out (Maj+F8)).
   • Step Over : Exécute la ligne courante sans entrer dans la fonction appelée, puis passe à la ligne suivante.
   • Step Into : Entre dans la fonction appelée sur la ligne courante pour en déboguer le contenu.
   • Step Out : Termine la fonction actuelle, puis revient à la ligne où elle a été appelée.
2. Grâce à l’exécution pas à pas, vous pouvez suivre l’évolution du flux de votre application et la valeur des variables.

8. Reprendre l’exécution

1. Cliquez sur le bouton « Reprendre le programme » (généralement une icône verte de lecture ou F9) dans l’IDE pour poursuivre le déroulement du code jusqu’au prochain point d’arrêt ou à la fin de l’exécution.

9. Consulter les résultats

1. Une fois l’exécution terminée, consultez les résultats affichés dans le navigateur (ou dans le terminal si vous déboguez en CLI). Pour cet exemple, le résultat attendu est :

   Debugging Example:
   Sum: 8
   Difference: 2
   Done.

Points d’attention

• Pare-feu : Assurez-vous que le pare-feu de votre système ne bloque pas le port utilisé par votre IDE pour l’écoute (par défaut : 9003).
• Conflit de port : Vérifiez que le port utilisé par XDebug n’est pas occupé par une autre application.
• Impact sur les performances : Avec xdebug.mode=debug et xdebug.start_with_request=yes, chaque requête PHP ouvre une session de débogage, ce qui peut dégrader nettement les performances. Désactivez XDebug ou basculez xdebug.start_with_request sur trigger lorsque vous n’avez pas besoin de déboguer.
• Débogage de scripts CLI : XDebug fonctionne aussi pour les scripts PHP exécutés en ligne de commande. Il faut alors utiliser une variable d’environnement ou des paramètres spécifiques pour déclencher le débogage (voir la documentation officielle XDebug).
• Version et configuration IDE : Les interfaces et options de configuration peuvent légèrement varier selon votre IDE et sa version. Consultez la documentation de votre outil pour un paramétrage détaillé.

Foire aux questions (FAQ)

Q : Mon IDE n’arrive pas à se connecter à XDebug, que faire ?

R : Vérifiez les points suivants :

1. Assurez-vous que le module XDebug est bien activé dans ServBay pour la version PHP concernée.
2. Contrôlez les paramètres xdebug.mode, xdebug.client_host, xdebug.client_port dans le fichier php.ini, et que client_host/client_port correspondent aux réglages d’écoute de l’IDE.
3. Si vous utilisez xdebug.start_with_request = trigger, vérifiez que vous ajoutez bien le déclencheur (paramètre GET/POST, Cookie, ou Header).
4. Vérifiez que votre pare-feu autorise le trafic sur le port XDebug.
5. Assurez-vous que votre IDE est bien en écoute sur ce port.

Q : Pourquoi mon site est-il lent après activation de XDebug ?

R : Cela provient généralement de l’option xdebug.start_with_request réglée sur yes. Ainsi, toutes les requêtes PHP tentent d’ouvrir une session de débogage, ce qui ajoute une surcharge importante. Préférez trigger pour ne déboguer que lors d’actions spécifiquement déclenchées.

Q : Puis-je déboguer des requêtes AJAX avec XDebug ?

R : Oui. Le principe de débogage AJAX est similaire à une requête HTTP classique. Assurez-vous simplement que la requête AJAX véhicule un déclencheur XDebug (souvent via un Cookie ou un Header).

Q : Outre PHPStorm, XDebug intégré à ServBay fonctionne-t-il avec VS Code ou d’autres IDE ?

R : Oui. La version intégrée de XDebug dans ServBay est compatible avec tous les IDE et éditeurs gérant le protocole DBGp, notamment VS Code (avec l’extension PHP Debug), NetBeans, Eclipse, etc. La configuration s’effectue de manière analogue, principalement au niveau du port d’écoute.

Conclusion

Avec l’intégration native de XDebug dans ServBay, déboguer vos projets PHP en local devient facile et efficace. Maîtrisez les points d’arrêt, l’inspection des variables ou l’exécution pas à pas afin de gagner du temps sur la localisation et la correction des bugs, tout en sécurisant la qualité de votre code. Grâce à la gestion simplifiée de ServBay, XDebug s’imposera comme un atout incontournable dans votre flux de travail PHP. Lancez-vous dès maintenant avec XDebug dans ServBay et profitez d’un développement PHP plus fluide et performant !