Xdebug

Xdebug est une extension PHP super utile pour… le débogage, comme son nom l’indique. Elle permet notamment le débogage pas à pas, inestimable ! Mais cette extension est un peu compliquée à configurer et peut fortement gréver les performances de votre ordinateur.

Tout le monde n’a pas la chance de travailler sur des frameworks modernes comme Symfony ou Laravel, qui possèdent leurs propres solutions de débogage. Parfois, il faut mettre les mains dans le cambouis et travailler sur du code legacy, mal ou pas documenté, à la logique obscure et au comportement abscons. Dans ce cas, disposer d’une solution qui permette d’arrêter le script à une ligne de code donnée pour connaitre la valeur des différentes variables à ce moment précis, puis relancer ligne à ligne le code pour suivre l’évolution des valeurs de ces variables, c’est vraiment très pratique.

Xdebug permet tout cela. Et bien plus. Je ne vais pas entrer dans le détail de ses possibilités ici, vous pouvez en apprendre plus sur le site officiel de l’extension. Non, je vais tenter d’expliquer comment régler un des plus gros problèmes de Xdebug…

Ma configuration

Avant tout, je vais vous expliquer ma configuration de travail au moment où j’écris ces lignes. Je dispose d’un ordinateur au capacités limitées, forcément sous Windows, car je travaille en entreprise. J’ai donc installé Wampserver afin de disposer d’une environnement de travail sous Apache, Mysql, et PHP. Et pour coder, pas de budget pour une licence PhpStorm, je me contente donc de VsCode.

La configuration de base de Xdebug se fait ainsi :

• On active l’extension via quelques lignes de code dans le php.ini.
• On installe une extension sur son navigateur pour permettre l’écoute de Xdebug sur ce navigateur, par exemple Xdebug Helper sous Firefox.
• On installe et on configure une extension sur VsCode, en l’occurrence PHP Debug par exemple.

Ensuite, pour utiliser Xdebug, il faut lancer l’extension du navigateur, lancer le débogage pas à pas dans l’IDE – ça se fait avec F5 dans VsCode -, poser un point d’arrêt sur la ligne de code qui nous intéresse et relancer la page de son site en local. Et là, magie, dans l’IDE, le code est exécuté ligne à ligne, mis en pause au niveau du point d’arrêt. Dans une fenêtre, on voit la valeur de toutes les variables en cours, c’est fantastique ! Et on peut faire défiler l’exécution du script ligne à ligne, c’est vraiment très pratique.

Xdebug a un problème

Je disais donc, Xdebug a un gros problème. Cette extension est intimement liée à PHP, et afin de pouvoir stopper un script à n’importe quel moment, elle écoute en permanence, elle n’est jamais en pause. Et elle scanne tout ce qui se passe au niveau du PHP. Tout. La conséquence ? Vos scripts mettent plus de temps à s’exécuter. Vraiment beaucoup plus de temps. En local, il m’arrivait d’attendre plusieurs dizaines de secondes avant que la page ne s’affiche complètement. Autant vous dire que, pour travailler, c’est insupportable.

Vous vous en doutez, tout cela est un problème de paramétrage. Si on ne fait pas attention, Xdebug tourne en tâche de fond en permanence sur votre serveur local de développement, ralentissant tout à un point extrême et insupportable. La solution est simple : il faut lancer Xdebug uniquement quand on en a besoin !

La solution

Pour paramétrer cela, la première chose est de vérifier votre php.ini. C’est le fichier de paramétrage de votre serveur PHP. Dans Wampserver, ce fichier est accessible ici : clic sur l’icône de Wampserver dans la barre des tâches, PHP, php.ini (apache module). Oui, faites attention, il y a deux versions du php.ini. La version Apache module est celle qui est utilisée par vos sites locaux, lancés via votre navigateur Internet. Mais il y a une autre version de php.ini pour la CLI, command line interface. Celle là est utilisée pour lancer PHP en ligne de commande. Xdebug y est un peu moins utile, mais il va quand même falloir se pencher sur sa configuration, au moins pour s’assurer que Xdebug ne tourne pas constamment.

Php.ini Apache module

Normalement, les lignes concernant Xdebug devraient se trouver en fin de fichier. Voilà à quoi cela devrait ressembler :

; XDEBUG Extension
[xdebug]
zend_extension="c:/wamp64/bin/php/php8.4.7/zend_ext/php_xdebug-3.4.2-8.4-ts-vs17-x86_64.dll"
;xdebug.mode allowed are : off develop coverage debug gcstats profile trace
xdebug.mode=debug
xdebug.start_with_request=trigger
xdebug.discover_client_host=false
xdebug.output_dir="c:/wamp64/tmp"
xdebug.show_local_vars=0
xdebug.log="c:/wamp64/logs/xdebug.log"
;xdebug.log_level : 0 Criticals, 1 Connection, 3 Warnings, 5 Communication, 7 Information, 10 Debug Breakpoint
xdebug.log_level=0
xdebug.profiler_output_name=trace.%H.%t.%p.cgrind
xdebug.use_compression=falseLangage du code : JavaScript (javascript)

Attention, votre configuration peut différer quelque peu. La ligne zend_extension donne le chemin vers l’extension. Il faut que vous utilisiez la version qui est fournie avec votre version de PHP.

xdebug.mode correspond au degré de verbosité de l’extension. Le mode debug est un bon compromis.

xdebug.start_with_request… Cette ligne fait toute la différence. C’est celle-là qu’il faut vérifier. Le mode trigger est le mode qui nous intéresse : il ne lancera Xdebug que si on le lui indique. Le reste du temps, elle ne prendra pas sur vos ressources pour rien.

Les autres lignes permettent de régler divers paramètres, je vous laisserais faire vos recherches.

Php.ini CLI

Afin de savoir quel est le fichier utilisé en ligne de commande, je vous invite à taper cela (dans votre ligne de commande) :

php --ini

Vous y trouverez le chemin du fichier à modifier, qui ne devrait pas être le même que celui pour Apache. Il se peut que vous n’ayez pas du tout de configuration pour Xdebug. Si vous en avez besoin en ligne de commande, vous pouvez utiliser la même portion de code que pour le module Apache. Le point le plus important est xdebug.start_with_request. Il faut lui spécifier le mode trigger sans quoi Xdebug risque de tourner constamment.

Une fois que vous avez effectué vos modifications dans les fichiers php.ini, relancez votre serveur : clic sur l’icône de Wampserver, Redémarrer les services.

Et VsCode ?

N’oublions pas VsCode… Dans la barre de gauche, il doit y avoir une icône de débogage, car vous avez installé précédemment l’extension PHP Debug. Elle ressemble à un triangle avec une coccinelle superposée. Un bug et un bouton de lecture.

Dans le panneau de débogage, en haut, cherchez la roue crantée intitulée open ‘launch.json’. En effet, il va nous falloir modifier ce fichier launch.json.

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch built-in server and debug",
            "type": "php",
            "request": "launch",
            "runtimeArgs": [
                "-S",
                "localhost:8000",
                "-t",
                "."
            ],
            "port": 9003,
            "serverReadyAction": {
                "action": "openExternally"
            }
        },
        {
            "name": "Debug current script in console",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "externalConsole": false,
            "port": 9003
        },
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "xdebugSettings": {
                "max_children": 128,
                "max_data": -1,
                "max_depth": 5
            },
            "env": {
                "XDEBUG_TRIGGER": "vscode"
            },
            "externalConsole": false,
            "runtimeExecutable": "C:\\wamp64\\bin\\php\\php8.4.7\\php.exe",
        }
    ]
}Langage du code : JSON / JSON avec commentaires (json)

C’est surtout le dernier bloc qui nous intéresse. Et en particulier la ligne XDEBUG_TRIGGER qui doit contenir soit « 1 » soit « vscode ».

Une fois ces modifications apportées, relancez VsCode.

Comment ça s’utilise ?

Tout d’abord, repérez dans votre script PHP un ligne qui vous intéresse, qui est utilisée par la page actuelle de votre site en développement. Dans la marge du code de VsCode, cliquez pour y faire apparaitre un point d’arrêt, breakpoint en anglais. Les points d’arrêt sont listés dans le panneau de débogage, en bas. Vous pouvez facilement naviguer de l’un à l’autre, les activer / désactiver, les supprimer…

Toujours dans VsCode, il faut lancer l’extension. Vous pouvez cliquer sur le bouton de lecture dans le panneau de débogage, ou appuyer sur F5. Une petite barre de lecture apparait :

• Pause.
• Step over : permet de passer à la ligne de code suivante.
• Step into : s’il y a une fonction, permet d’entrer dans la fonction.
• Step out : sort de la fonction si vous y étiez.
• Restart : permet de relancer.
• Stop : arrête le script. Vous aurez sans doute une page blanche…

Dans votre navigateur, sur la page de votre site en développement, dans la barre d’URL, vous devez avoir une icône qui représente une coccinelle. En cliquant dessus, vous pouvez activer ou désactiver l’écoute de Xdebug. C’est là que vous demandez à Xdebug de fonctionner ou non, de prendre des ressources pour vous donner des informations – c’est le mode debug -, ou vous laisser de la ressource et de la fluidité – c’est le mode disable.

Et quand vous avez fini ?

• Dans VsCode, arrêter le mode débogage en cliquant sur le bouton Stop.
• Dans votre navigateur, un clic sur la coccinelle pour mettre à Disable.

Cela met Xdebug en pause, ça arrête l’écoute constante et l’analyse de tous les fichiers PHP qui tournent, et ça libère de la ressource. Votre site retrouve sa vélocité attendue.