Configurer Xdebug avec PHP 8 et deboguer pas à pas

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 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 nouvelle fonction var_dump() mais permet surtout, et c'est ce qui nous intéresse, de déboguer pas à pas avec un client (VSCode, PHPStorm, ce que vous voulez en fait).

Configurer Xdebug

Pour configurer XDebug, il faut modifier le fichier ini qui va bien. Pour ma part, comme j'utilise php-fpm sur mon poste, je vois bien le fichier de configuration qui nous interesse /etc/php/8.4/fpm/conf.d/20-xdebug.ini -> /etc/php/8.4/mods-available/xdebug.ini. Donc en général en cherchant dans /etc/php vous trouverez le fichier de configuration qui va bien.

On va rajouter ceci à 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, c'est pour ne pas avoir des warnings gênants en mode CLI. Comme Xdebug: [Step Debug] Could not connect to debugging client. Tried: 127.0.0.1:9003 (through xdebug.client_host/xdebug.client_port).. Cela pour gêner des scripts.

Cette configuration est valable pour Xdebug3 soit un version de version 8 et plus.

Déboguer Pas à Pas dans VSCode

Commencez par créer un nouveau fichier dans votre projet .vscode/launch.json vous y mettrez le code suivant.

{
   "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
           }
       },
   ]
}

On peut ensuite appuyer sur F5 pour que notre IDE se mette à écouter sur le port 9003 sur la boucle locale.

Maintenant, il va suffire de déclencher PHP avec la CLI (ligne de commande ou un appel via un serveur Web par exemple).

Testez en ligne de commande pour simplifier les choses en commence par mettre un point d'arrêt dans un simple fichier test.php pas exemple.

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

Sachez que si votre point d'arrêt de ne déclenche pas, cela sera presque toujours un problème de communication entre votre IDE (qui doit écouter sur un port) et celui qui exécute PHP (le CLI, Apache, Nginx ou Php-FPM).

Pensez aussi à votre version de PHP, la version 7 utilise XDebug2 et la version 8 et plus utilise XDebug 3.

Bon courage !