Passer au contenu

Configurer Xdebug avec PHP 8 et déboguer pas à pas

Comment installer, configurer Xdebug et déboguer son code efficacement.

Cet article va décrire comment activer Xdebug avec PHP 8 et les versions supérieures.

Il faut tout d'abord prendre conscience qu'avec le passage à PHP 8 depuis la version 7, la version de Xdebug est passée de 2 à 3. Les paramètres de configuration varient selon votre version.

Installer Xdebug

Pour installer Xdebug, soit vous êtes sur Windows (je conseille d'utiliser WSL), soit sur Linux et vous installez php8.4-xdebug par exemple : sudo apt install php8.4-xdebug si vous êtes sur une distribution dérivée d'Ubuntu.

Le plus simple pour obtenir la bonne configuration est d'utiliser ce lien : https://xdebug.org/wizard.
Il suffit de copier le contenu de la fonction phpinfo() dans cet utilitaire pour avoir une description de votre installation de Xdebug.
Vous pouvez obtenir ce contenu directement depuis le terminal avec php -i.

L'installation de Xdebug fournit une fonction var_dump() enrichie mais permet surtout, et c'est ce qui nous intéresse, de déboguer pas à pas avec un client (VS Code, PhpStorm, etc.).

Configurer Xdebug

Pour configurer Xdebug, il faut modifier le fichier ini approprié. Pour ma part, comme j'utilise php-fpm sur mon poste, le fichier de configuration est /etc/php/8.4/fpm/conf.d/20-xdebug.ini -> /etc/php/8.4/mods-available/xdebug.ini. En explorant /etc/php, vous trouverez le fichier correspondant à votre version.

Ajoutez la configuration suivante à l'intérieur :

xdebug.log_level = 0
xdebug.start_with_request = yes
xdebug.mode = debug,develop
xdebug.client_port = 9003
xdebug.client_host = 127.0.0.1

Le log_level = 0 permet d'éviter les avertissements intempestifs en mode CLI (tels que Xdebug: [Step Debug] Could not connect to debugging client...) qui pourraient gêner l'exécution de scripts.

Cette configuration est valable pour Xdebug 3 avec PHP 8 et versions supérieures.

Déboguer pas à pas dans VS Code

Créez un nouveau fichier dans votre projet à l'emplacement .vscode/launch.json contenant :

{
   "version": "0.2.0",
   "configurations": [
       {
           "name": "Listen for Xdebug",
           "type": "php",
           "request": "launch",
           "hostname": "localhost",
           "port": 9003,
           "xdebugSettings": {
               "max_children": 256,
               "max_data": 1024,
               "max_depth": 3
           }
       }
   ]
}

Appuyez ensuite sur F5 dans VS Code pour démarrer l'écoute sur le port 9003 en local.

Il suffit maintenant de déclencher une exécution PHP (ligne de commande ou requête HTTP via Apache/Nginx).

Pour tester facilement en CLI, placez un point d'arrêt dans un fichier de test simple test.php.

Capture d'écran de débogage pas à pas avec VS Code et PHP

Vous voilà prêt à déboguer efficacement votre code.

Si votre point d'arrêt ne se déclenche pas, cela provient généralement d'un problème de communication réseau ou de port entre votre IDE et le processus exécutant PHP (CLI ou PHP-FPM).

Bon débogage !

juniko
3 min