Débogage pas à pas avec Xdebug, Symfony et PHPStorm

Publié le 21/06/2020 • Actualisé le 18/10/2020

Dans cet article nous allons voir comment déboguer pas à pas avec Xdebug, Symfony et PHPStorm. Nous verrons un exemple basique ou nous stopperons l'exécution du code du contrôleur juste avant le rendu du template pour vérifier les données que nous lui passons. C'est parti ! 😎

» Publié dans "Une semaine Symfonique 704" (du 22 au 28 juin 2020).

Prérequis

Je présumerai que vous avez les compétences de base concernant Symfony et que vous savez modifier votre configuration PHP grâce au fichier php.ini.

Introduction

Pourquoi cet article ? À cause de ce tweet :

Les développeurs PHP qui n'utilisent pas Xdebug pour déboguer sont des amateurs.

— Derick Rethans 🔶 (@derickr) June 20, 2020

“Les développeurs PHP qui n'utilisent pas Xdebug pour déboguer sont des amateurs.”

C'est le genre de tweet que je n'aime pas, un troll typique, qui essaie de faire une généralité de quelque chose de plus subtil. Ça provoque de la négativité dans la communauté car ça peut être interprété par les gens n'utilisant pas Xdebug par :

“Si vous n'utilisez pas Xdebug, vous n'êtes pas un vrai développeur.” 😔

Même si ce n'est pas ce que Derick veut dire, c'est quelque chose que les gens peuvent comprendre. Il n'y a pas de smiley. On ne sait pas si c'est du pur sarcasme ou pas. Je voulais répondre dans un premier temps. Puis, je me suis dit, pourquoi ne pas transformer quelque chose de négatif en quelque chose de positif et utile ? 😀 C'est pourquoi j'ai décidé d'écrire cet article. 🙂

Configuration

J'utilise la configuration suivante mais ça devrait être bon avec des versions précédentes (pas trop anciennes) de chacun de ces composants. Ici, j'utilise le binaire Symfony pour servir mon application. Si vous avez un autre type de configuration (Apache, Docker...), vous devrez probablement faire quelques ajustements dans les instructions suivantes.

• PHP 8.3
• Symfony 6.4
• Xdebug 2.9.6
• PHPStorm 2023.3.3

Installation

Je supposerai que vous avez une installation PHP / Symfony fonctionnelle. Donc tout d'abord, installons Xdebug, ça peut être fait avec PECL :

pecl install xdebug

Si ce n'est pas fait, activez l'extension Xdebug dans votre fichier php.ini. Vous pouvez trouver ce fichier en lançant la commande :

$ php -i | grep php.ini
Configuration File (php.ini) Path => /usr/local/etc/php/7.4
Loaded Configuration File => /usr/local/etc/php/7.4/php.ini

Vérifiez que dans de fichier, la librairie xdebug.so (ou .dll) est chargée. Vous devez voir une ligne identique (elle peut aussi être chargée à partir d'un fichier externe comme conf.d/ext-xdebug.ini) :

zend_extension="xdebug.so"

Si tout est bon, vous devriez voir Xdebug quand on affiche la version de PHP :

$ php -v
PHP 7.4.6 (cli) (built: May 14 2020 10:39:21) ( NTS )
Copyright (c) The PHP Group
Zend Engine v3.4.0, Copyright (c) Zend Technologies
    with Xdebug v2.9.6, Copyright (c) 2002-2020, by Derick Rethans
    with Zend OPcache v7.4.6, Copyright (c), by Zend Technologies

Ou en cherchant dans la liste des modules activés :

$ php -m | grep xdebug
xdebug

La barre de debug indique aussi si Xdebug est disponible quand vous passez au dessus du numéro de version de Symfony avec votre souris :

Maintenant que Xdebug est activé, voyons comment le configurer pour l'utiliser en conjonction avec PHPStorm.

Configuration de Xdebug et PHPStorm

Xdebug

Premièrement nous devons activer l'option remote de Xdebug. Ajoutez le paramètre suivant dans votre configuration comme nous l'avons vu précédemment :

xdebug.remote_enable=1

Nous garderons les autres paramètres par défaut afin de garder la configuration aussi succincte que possible. Ceci étant dit, le port par défaut de Xdebug est 9000 alors que l'adresse IP est 127.0.0.1. Veuillez consulter la documentation des deux paramètres xdebug.remote_host et xdebug.remote_port.

PHPStorm

Maintenant voyons la configuration relative à PHPStorm. Ouvrez l'entrée de menu Run > Web Server Debug Validation. Vous devriez accéder à cette fenêtre :

Dans le premier paramètre, mettez le chemin complet du répertoire public de votre projet, c'est le répertoire où est stocké le contrôleur d'entrée Symfony (généralement public/index.php avec Symfony 5). Dans le second paramètre, mettez l'URL locale de votre projet. Puis, cliquez sur Validate. Si tout est bon, vous devriez voir des ✅ comme ci-dessus. Vous pouvez ignorer l'erreur de la dernière ligne, il semble que ce soit un problème connu mais ça n'empêchera pas le débogueur de fonctionner. La dernière étape est d'activer l'écoute des connexions XDebug par PHPStorm. Ça doit être fait avec l'entrée de menu Run > Start Listening for PHP Debug connections.

Débogage pas à pas

Maintenant que PHPStorm a validé notre configuration essayons d'ajouter notre premier point d'arrêt. Ouvrez l'un de vos contrôleurs et cliquez entre le numéro de ligne et le début du panneau d'édition de code de la ligne où vous voulez stopper l'exécution. Un disque rouge 🔴 apparait sur cette ligne comme ceci (à la ligne 33 dans l'exemple ci-dessous).

Maintenant, ouvrez votre navigateur et accédez à une page appelant l'action où nous venons de mettre ce point d'arrêt. Si ça fonctionne bien, PHPStorm revient en tant que fenêtre active de votre système d'exploitation et on a la sortie suivante :

Comme vous pouvez le voir, la fenêtre d'édition du code est différente de ce que nous avons l'habitude de voir. Tout d'abord, après la ligne de déclaration de la méthode action, on a les valeurs des paramètres reçus par l'action. $_locale a pour valeur "en", $goals est un tableau contenant deux clés et enfin $articleRepository est le dépôt Doctrine de l'entité Article. Juste en dessous, nous voyons que la ligne du point d'arrêt est surlignée ; c'est pour montrer que le code s'est bien arrêté à cette ligne comme attendu. Juste avant cette ligne, après la déclaration de $data (à la droite), on voit la valeur de celle nouvelle variable. Elle est vide puisque nous venons de la déclarer. En dessous, dans le panneau de debug, nous avons une section Variables qui permet d'inspecter toutes les variables locales disponibles au point d'arrêt.

Ce panneau est très pratique ; on peut voir toutes les variables (même les globales) et les déplier pour vérifier leur contenu. Nous trouvons aussi les paramètres de la fonction ($_locale, $goals, $articleRepository). Comme ce contrôleur étend le contrôleur abstrait Symfony, on peut remarquer que celui-ci a accès à l'injection de dépendances ($this->container).

Maintenant essayons d'avancer d'un "pas" en allant à la ligne suivante. On peut utiliser le bouton Step over (F6 avec ma configuration).

Comme vous pouvez le voir, la ligne surlignée a changé, c'est maintenant la ligne n°34. Nous pouvons désormais voir la valeur de la variable $date juste au dessus. Cette nouvelle variable fait son apparition dans le panneau de debug "Variables". Nous pouvons continuer de la sorte jusqu'à la fin de l'action afin de vérifier que le tableau $data contient bien les bonnes clés et valeurs et qu'il peut donc être passé au template Twig. Pour continuer l'exécution de la page, cliquez sur le bouton Resume program ⏯️ (F8).
Si vous n'avez plus besoin de ce point d'arrêt mais que vous voulez le garder pour plus tard, vous pouvez faire un clic droit sur celui-ci et décocher l'option Enabled. Le disque rouge devient un cercle. Rafraichissez la page, on constate que le script n'est plus arrêté.

L'extension de navigateur

On peut aussi installer une extension de navigateur (disponible pour Firefox, Chrome, Safari, Opera) pour désactiver / activer le debug à la volée. Si désactivé, rien n'est intercepté par PHPStorm même s'il y a encore des points d'arrêt actifs. C'est plus pratique que de désactiver les points d'arrêts manuellement ou encore de désactiver complétement Xdebug dans la configuration PHP. Ça ressemble à ceci :

Conclusion

Et voilà ! Nous avons un processus de débogage pas à pas fonctionnel en utilisant Xdebug ! Et si nous disions à Derick que nous sommes désormais des développeurs professionnels ? 😁

À propos du tweet original, j'ai beaucoup aimé la réponse de Jordi ; c'est précisément ce que je pense :

I can see a debugger being valuable when code is very complex or unknown, and often use it in JS. In PHP code though I usually am familiar enough with what libs I use and find no benefit to debugging interactively. Like most things, it depends. No need to call people amateurs IMO

— Jordi Boggiano (@seldaek) June 20, 2020

Pour voir quelques tweets parodiques de l'original, cliquez sur ce lien 😜.

If you don't drink Guinness you are an amateur

— Gary Hockin (@GeeH) June 20, 2020

PHP developers who don’t use @doctrineproject are amateurs.

— Jonathan H. Wage (@jwage) June 20, 2020

Developers that don't use a computer to develop are amateurs

— Gregoire Pineau (@lyrixx) June 21, 2020

PHP developers that don't write there own frameworks are amateurs

— Simon Bennett (@MrSimonBennett) June 20, 2020

PHP developers that write bugs and need to debug are amateurs. https://t.co/NG5YtmdD3k

— Liam Hammett (@LiamHammett) June 20, 2020

Et voilà ! J'espère que vous avez aimé. Découvrez d'autres informations en rapport à cet article avec les liens ci-dessous. Comme toujours, retours, likes et retweets sont les bienvenus. (voir la boîte ci-dessous) À tantôt ! COil. 😊

  Lire la doc  Plus sur le web  Plus sur Stackoverflow

Ils m'ont donné leurs retours et m'ont aidé à corriger des erreurs et typos dans cet article, un grand merci à : jmsche. 👍

  Travaillez avec moi !

---