Installer et utiliser Xdebug 3 pour VSCode et sous Windows

1. Ouvrez une invite de commande : Touche Windows + R puis tapez cmd. Tapez php -i puis copier le résultat et coller le dans l'assistant Xdebug (* Voir figure ci-dessous).

   

2. Demandez l'analyse.
3. Téléchargez la librairie qui vous est proposée.

   

4. Renommez la en php_xdebug.
5. Copiez là dans le répertoire qui contient vos extensions PHP. Pour mon installation c'est C:\Program Files\PHP\ext.
6. Ouvrez le fichier php.ini. Ajouter les lignes suivantes à la fin du fichier. [XDEBUG] zend_extension=xdebug xdebug.mode=debug,develop ;xdebug.start_with_request = yes ;xdebug.start_with_request = trigger

   Par rapport à Xdebug 2, peut être que vous constaterez une différence concernant la valeur de xdebug.mode. En fait pour Xdebug 3 la valeur debug vous donne le "pas à pas" du débogueur et la valeur develop vous permet d'avoir la surcharge du var_dump php et la mise en forme des messages d'erreurs. Vous avez les explications sur le setting des modes sur le site officiel xdebug.org.

7. Maintenant passons à VSCode. Lancez le et faites CTRL+MAJ+X pour accéder à la place de marché des extensions. Recherchez l'extension Xdebug en tapant les mots-clés PHP Debug. Il y a plusieurs résultats. Choisissez l'extension la plus populaire qui appartient à xdebug.org. Installez là et c'est terminé 😉 .

1. A droite du schéma ci-dessous, vous avez la partie IDE avec l'extension que nous avons installée.
2. A gauche, vous avez la partie navigateur avec le serveur et son PHP avec la dll que nous avons installée.
3. Les deux parties sont reliées par un canal de communication sur lequel circulent des informations qui supportent le protocole DBGP pour DeBuGer Protocol. 😄

4. Côté IDE, lorsque l'on démarre une session de débogage, il va se mettre en attente d'une connexion sur un port du canal de communication.
5. De l'autre côté il va falloir prévenir le serveur qu'il doit faire une session de débogage et qu'il devra se connecter à l'IDE par le canal de communication. Il y a plusieurs moyens de faire ça. Le plus simple étant de mettre une variable dans l'URL au niveau du navigateur. On verra à la fin du tuto d'autres moyens pour faire ça.

1. Créez un répertoire Test-Xdebug. Ouvrez VSCode. Créez un fichier index.php. Copiez / Collez le code ci-dessous dans le fichier. <?php // xdebug_break(); function f1() { f2(); } function f2() { f3(); $reprise =true; } function f3() { echo $tmp; var_dump($_SERVER); } $my_int = 1; $my_bool = true; $my_bool = false; $my_str = 'Ma chaine'; f1();
2. Démarrage du serveur. Bien sûr il nous faut un serveur pour exécuter notre code. Je vais prendre le serveur interne à PHP. Pour cela j'ouvre le terminal VSCode et je tape php -S localhost:4000. Le choix du numéro de port est arbitraire.
3. Démarrage du débogueur. Maintenant cliquez sur l'icône de gauche Exécuter et Déboguer (*Figure ci-dessous en 1). Vous avez un raccourci pour le faire CTRL+MAJ+D. Lors de la première session de débogage sur un projet, il vous faudra créer un fichier launch.json (* Figure ci-dessous en 2). Ce fichier est créé dans le dossier .vscode. Il doit être créé pour chaque projet. Il contient plusieurs configurations de lancement de l'IDE. On y trouve notamment le numéro de port, à savoir 9003, sur lequel l'IDE attend la connexion du serveur.

   

4. Mise en place des points d'arrêt. Je vais les mettre sur les lignes 14, 16 et 19. Vous avez la figure ci-dessous.

   

5. Choix du type de session de débogage. Vous pouvez déboguer avec le navigateur mais vous pouvez aussi si c'est possible déboguer avec la console de débogage. Si vous déboguer avec le navigateur vous avez les résultats de l'exécution dans le navigateur. Si vous déboguer avec la console de débogage et bien vous avez les résultats de l'exécution dans la console de débogage.

   

6. Démarrage de la session de débogage. Vous pouvez utiliser le raccourci F5 ou passer par le menu Exécuter ou cliquez sur le triangle vert (* voir figure de dessus). A ce stade l'IDE attend la connexion du serveur. La barre de status est passée en orange. Le panneau de contrôle du débogueur est apparu mais il est inactif.
7. Lancement du navigateur. Il faut le lancer en mettant une variable XDEBUG_SESSION égale à une valeur quelconque. C'est par ce moyen que vous prévenez le serveur qu'il doit faire une session de débogage et qu'il doit communiquer avec l'IDE. Il va communiquer avec l'IDE en utilisant la php_xdebug.dll que nous avons installée. Si vous ne mettez pas la variable il ne communiquera pas et il exécutera la requête. Et vous, vous demanderez pourquoi ça ne marche pas ! 🤔

Ci-dessous description des icônes de contrôle du pas à pas

1. Je vais cliquer sur Continuer pour aller de la ligne 14 à la ligne 16. Vous voyez que là, je ne fais pas du pas à pas, je fais du point d'arrêt à point d'arrêt. Et s'il n'y a plus de point d'arrêt je vais jusqu'au bout.
2. Maintenant je clique sur Step Over ou sur Step in pour passer de la ligne 16 à la ligne 17. Je fais encore un step in pour aller à la ligne 19 devant l'appel de la fonction. Observez la valeur des variables dans la fenêtre de gauche.
3. Je clique sur Step in pour descendre dans la fonction f1. Puis encore un Step in pour descendre dans f2 puis encore un pour descendre dans f3. Regardez la pile des appels.
4. Maintenant je veux sortir de f3 je fais donc un step out et vous voyez que je retourne juste en dessous de l'appel à f3.
5. Je fais deux step out pour remonter à la fin de f2 puis à la fin de f1.
6. L'exécution est terminée. Regardez le résultat dans le navigateur. Grâce au mode develop (* ligne xdebug.mode=debug,develop du php.ini) vous avez la mise en forme des erreurs et l'amélioration du var_dump() PHP 😃.

Au moment de lancer la session de débogage dans l'IDE il faut que je choisisse Launch currently open script. Voir ci-dessous. Ensuite je démarre l'exécution au moyen du panneau de contrôle. Par contre je n'ai plus besoin de lancer le navigateur. Vous pouvez voir les résultats de l'exécution dans la console de débogage et c'est à cette condition que vous pouvez choisir ce type de session.

1. Au moyen du navigateur dans l'Url, à la place de XDEBUG_SESSION vous pouvez utiliser XDEBUG_SESSION_START. Ca va avoir pour effet de créer un cookie et tant que ce cookie existera alors le serveur démarrera en mode débogage. Pour supprimer le cookie vous devrez faire une session avec XDEBUG_SESSION_STOP ou bien effacer les cookies.
2. En configurant le serveur au niveau du php.ini. On peut démarrer systématiquement le serveur en mode débogage en mettant la directive xdebug.start_with_request = yes . Donc là littéralement vous dites au serveur : démarre une session de débogage à chaque requête. Le problème c'est que si du côté IDE vous n'avez pas l'intention de faire une session de débogage et bien il ne sera pas en attente de connexion et vous aurez un message d'erreur serveur (* Time-out connecting to debugging client). On peut aussi mettre la directive xdebug.start_with_request = trigger. Dans ce cas dans le code php il faut mettre l'instruction xdebug_break();.
3. Il est aussi possible déboguer si vous utilisez php en ligne de commande. Dans ce cas il faut avoir recours à une variable d'environnement Windows. Une variable utilisateur suffit.
4. Enfin il y a des extensions pour les navigateurs. Je n'ai pas eu de bons résultats avec celles que j'ai essayées 😬. Si la situation évolue je mettrais à jour à ce moment là 😆.

Je précise que je n'ai pas utilisé deux fonctionnalités importantes : la fonction trace et la fonction profiler. J'essaierai de faire ça dans d'autres tutoriels sur des exercices qui seront adaptés.