Déboguer en PHP avec l'extension Xdebug et l'IDE PhpStorm
Si vous utilisez les var_dump() et echo() pour déboguer vos applications PHP, il va falloir changer vos mauvaises habitudes ! Cet article vous explique pas à pas, comment mettre en place le débogage en PHP grâce à l'extension Xdebug. Attention dans cet article, je n'explique pas le principe du débogage ni de comment fonctionne l'extension Xdebug. On se concentre uniquement sur la mise en place du débogage. Si vous voulez en savoir plus, je vous invite à aller lire la documentation officielle.
Prérequis
Bien évidemment, l'extension PHP Xdebug doit être installée. Pour vérifier si l'extension est déjà installée dans votre environnement, tapez la commande :
php --ri xdebug
Si la commande indique que l'extension n'est pas présente, il faut alors l'installer. Je vous laisse faire, ce n'est pas bien compliqué.
Configuration de l'extension Xdebug
Vous devez ensuite modifier un des fichiers de configuration de PHP pour paramétrer Xdebug. Sur Ubuntu, il existe un fichier de configuration spécifique pour Xdebug. Vous pouvez le trouver à l'adresse suivante : /etc/php5/apache2/conf.d/20-xdebug.ini. Il faut rajouter les lignes ci-dessous :
xdebug.remote_enable=1
xdebug.remote_connect_back=1
xdebug.remote_port=9000
xdebug.remote_enable permet d'activer le débogueur Xdebug sur le serveur.
xdebug.remote_connect_back permet d'indiquer à Xdebug qu'il doit essayer de se connecter au client qui a effectué une requête HTTP. Pour cela, il utilise l'IP contenu dans la variable $_SERVER['REMOTE_ADDR'].
xdebug.remote_port permet d'indiquer le port d'écoute du client. On garde la valeur par défaut qui vaut 9000.
A la place de xdebug.remote_connect_back, vous pouvez utiliser xdebug.remote_host. Ce paramètre permet d'indiquer directement l'IP du client. Vous pouvez ainsi contrôler qui peut se connecter à votre serveur en mode débogage.
Une fois les lignes ajoutées, redémarrez Apache. Sur Ubuntu :
sudo service apache2 restart
Si vous faites un phpinfo(), la configuration de Xdebug devrait avoir changé maintenant :
Activation du débogueur de Xdebug
Pour activer le débogueur sur le serveur, il est nécessaire de créer un cookie au niveau du client. Ce cookie doit porter le nom spécifique XDEBUG_SESSION et doit contenir une clé. Si vous voulez plus de détails, vous pouvez lire la documentation sur le site officiel de Xdebug.
La création du cookie peut se faire manuellement mais il existe beaucoup d'extensions de navigateurs qui peuvent faire ce boulot. Installez donc l'extension de votre choix. Personnellement sur Firefox, j'utilise l'extension Xdebug-ext
Allez dans Outils >> Modules complémentaires, puis dans l'onglet Extensions. Au niveau de l'extension Xdebug-ext, cliquez sur le bouton Préférences :
Dans la nouvelle fenêtre qui s'ouvre, indiquez la clé du cookie, par exemple phpstorm-xdebug :
Ensuite pour créer le cookie, vous n'avez plus qu'à cliquer sur le nouveau bouton qui est apparu en haut à droite de la fenêtre de Firefox :
Quand vous cliquez dessus, l'icône devient rouge :
Configuration de l'IDE
Dans cette partie, je vais décrire la procédure à suivre pour PhpStorm mais si vous utilisez un autre IDE, il faut suivre la même logique.
Dans un premier temps, il Il est nécessaire de demander à son IDE d'écouter les connexions entrantes. Pour cela, cliquez sur l'icône en haut à droite de la fenêtre de PhpStorm. Vous pouvez également utiliser le menu : Run >> Start Listening For PHP Debug Connections :
L'icône change alors de couleur :
Il faut ensuite indiquer à son IDE qu'il va être contacté par Xdebug. Ouvrez la fenêtre File >> Settings. Allez dans Languages & Frameworks >> PHP >> Debug. Vérifiez que le port est bien égal à 9000 et que les connexions externes sont bien acceptées :
Ensuite allez dans Languages & Frameworks >> PHP >> Server. Il faut créer un nouveau serveur en indiquant l'IP et le port de votre serveur. Dans la liste des débogueurs, il faut indiquer Xdebug. Il peut être nécessaire également de faire un mapping entre l’arborescence du projet dans votre IDE et l'arborescence du projet sur le serveur. Ici dans l'exemple présenté, il n'est pas nécessaire de le faire car le client et le serveur sont sur la même machine (localhost) et partage la même arborescence :
Lancement du débogage
Dans l'IDE, ajoutez un point d'arrêt dans le code de votre site :
Dans votre navigateur, activez le cookie grâce à l'extension installée au début de cet article, puis allez sur le site hébergé par votre serveur. L'IDE va prendre le focus en vous indiquant qu'il y a une connexion entrante :
Acceptez, vous pourrez alors déboguer pas à pas et voir le contenu des différentes variables dans le nouvel espace prévu à cet effet :
Et si je veux déboguer un script qui est lancé en ligne de commande ?
Bonne nouvelle, c'est également possible. Précédemment, nous avons configurer Xdebug en modifiant les fichiers de configuration de PHP spécifiques à Apache. Ici, il faut ajouter la même configuration mais cette fois-ci en modifiant les fichiers de configuration PHP spécifiques à la ligne de commande (CLI).
Ensuite il suffit de créer une variable d'environnement avant d'exécuter son script. Elle contient le nom de la clé créée au début de cette article, ce qui permet d'activer le débogage. Sur Linux :
export XDEBUG_CONFIG="idekey=phpstorm-xdebug"
php nom_du_script.php
Si vous êtes sur Windows :
set XDEBUG_CONFIG="idekey=phpstorm-xdebug"
php nom_du_script.php
Cette méthode fonctionne si vous codez et exécutez le script sur la même machine. Si vous codez sur votre machine locale et que vous voulez exécutez le script sur une autre machine via SSH par exemple, alors il faut suivre la méthode un peu plus complexe ci-dessous :
1) Il faut toujours créer la variable d'environnement XDEBUG_CONFIG, mais cette fois-ci, il faut donner en plus l'IP de la machine où vous codez. Cela nous donne :
export XDEBUG_CONFIG="idekey=phpstorm-xdebug remote_host=xxx.xxx.xxx.xxx"
2) Il y a ensuite une étape supplémentaire. Il faut créer une autre variable d'environnement nommée PHP_IDE_CONFIG qui va permettre à PhpStorm de savoir avec quel serveur il doit communiquer. Normalement dans la partie Configuration de l'IDE situé plus haut dans cet article, vous avez configuré un serveur en lui donnant un nom (fenêtre Settings, partie Languages & Frameworks >> PHP >> Server). Il faut reprendre ce nom et l'assigner à cette variable. Par exemple si le serveur s'appelle mon.serveur.dev, cela nous donne :
export PHP_IDE_CONFIG=serverName=mon.serveur.dev
3) Vous pouvez maintenant exécuter le script sur le serveur :
php nom_du_script.php
Si tout est OK, le débogage doit se lancer dans PhpStorm.
Version
Cet article a été testé avec :
PHP : 5.6.
PhpStorm: 8.0
Xdebug : 2.2.6
Ubuntu : 15.04