[Outils pour développeurs] XDebug - débugger vos script PHP


par ericc

Ceci est une recopie de 2 articles que j'avais écrit sur le forum de l'OGSTeam (développeurs de OGSpy)

1 - Introduction

Débugger une application php peux parfois s'avérer une véritable prise de tête. Comparé avec d'autres langages de programmation, l'aspect orienté "web" de php ne simplifie pas la tache.
Bien sur, on peux utiliser des "echo", des "print_r", voir même des "var_dump" mais ce n'est pas très convivial (n'est ce pas) et on peux passer à coté de choses importantes.

Je vais vous présenté une petite librairie qui rend bien des services et simplifie beaucoup de débuggage surtout dans les cas complexe.

2 - Présentation

XDebug est une librairie libre et Open-Source, et s'installe comme une extension de PHP. Elle est souvent présentée comme "le couteau Suisse" du développeur PHP.
Elle est compatible Linux (Unix) et Windows.

3 - Limitations

Je commence à peine, et déjà je parle de limitations :rolleyes: !!!
Xdebug étant une extention de PHP, vous devez avoir accès en temps qu'administrateur (ou root) à votre serveur !!!
Vous devez avoir accès au php.ini de l'installation PHP.
De plus, lorsqu'elle est active, il y a un ralentissement du système, surtout lorsqu'il y a des erreurs. Certains scripts particulièrement "mal" codé provoque tellement d'erreurs qu'ils en deviennent presque inutilisable (phpMyAdmin par exemple :o )
Sans parler des messages d'erreurs quelle provoque qui pourrais dérouter un utilisateur lambda , voir même présenter un problème de sécurité (affichage des mots de passe)

Donc vous l'aurez compris, cette librairie ne peux être utilisé QUE sur un serveur de "développement".
Mais quoi !! Vous êtes des développeurs sérieux, vous avez tous un serveur de développement sur lequel vous faites vos tests :rolleyes:
Donc il n'y a pas de problème ....

4 - Installation

Si votre serveur est sous Windows (XP ou Vista), vous devez downloader le module qui correspond à votre version de PHP (page principale de Xdebug : "Windows modules" .
Et le copier dans le répertoire des extensions de votre installation PHP

Si votre serveur est sous Linux (comme il se doit ) , vous avez deux choix:
Soit downloader les sources et compiler
Soit utiliser le PECL natif à PHP. Cette méthode est préférable car de loin la plus simple.
-> Dans une console terminal, tapez :
pecl install xdebug

et c'est tout !!! En règle générale cela fonctionne assez bien
remarque : Si vous utilisez une installation tout intégrée dans le style de LAMPP (ou XAMPP pour Linux), le pecl risque de ne pas fonctionner. Pour contourné ce petit problème, soit vous ajouter le répertoire de php dans votre path, soit vous installez les packages php qui correspondent à votre distribution.
apt-get install php5-dev

sous Debian et Ubuntu

Si la méthode pecl ne fonctionne pas (too bad !) vous devrez compiler le module manuellement.
Outre que PHP doit être installé, vérifiez que vous avez aussi le minimum des outils de compilation (Autoconf, Automake et Libtool)
Sous Debian et Ubuntu, un petit :
apt-get install build-essential

règle la question.

Ensuite, rien de sorcier :
wget
tar -xzf xdebug-2.0.3.tgz
cd xdebug-2.0.3
phpize
./configure --enable-xdebug --with-php-config=/usr/bin/php-config
make
cp modules/xdebug.so //modules/xdebug.so

Changez "xdebug203" par la dernière version disponible

Enfin, il faut activer le module.
Pour cela, il faut éditer le fichier php.ini et ajouter :
sous Windows
zend_extension_ts="c:\php\ext\php_xdebug-2.0.1-5.2.1.dll"

sous Linux
zend_extension="/usr/lib/apache2/modules/xdebug.so"

Remplacez les chemins par ceux de votre installation !!!!


Pendant que vous êtes dans le php.ini, recherchez :
error_reporting = E_ALL & ~E_NOTICE

et remplacez par :
error_reporting = E_ALL

pour être sur de voir TOUTES les erreurs, même les erreurs de Notice qui sont parfois révélatrice de problèmes plus important et comme dirait notre ami Unibozu :
Ça t'apprendra à bien coder dès le début
©Unibozu-2008

(merci à toi, c'était un conseil judicieux )

Vous sauvegardez et vous redémarrez votre serveur Apache.

Un petit tour par phpinfo() pour vérifier que tout va bien :

(tiens il va falloir que je mette à jour)

Ouf , passons à la suite

5 - Configuration

Pour configurer XDebug, vous avez deux possibilités:
Soit vous créez une section [xdebug] dans php.ini
Soit au coup par coup, avec un
ini_set('xdebug.', );

au début du script.

Personnellement, je préfère la méthode permanente dans le php.ini .

var_dump()
Xdebug améliore la présentation de var_dump() le rendant plus lisible exemple de la sortie de l'array $server_config )
array
'allied' => string '' (length=0)
'ally_protection' => string '' (length=0)
'debug_log' => string '0' (length=1)
'default_skin' => string 'http://192.168.28.55/ogspy/skin/OGSpy_skin/' (length=43)
'disable_ip_check' => string '1' (length=1)
'keeprank_criterion' => string 'day' (length=3)
'last_maintenance_action' => string '1208728800' (length=10)
'max_battlereport' => string '10' (length=2)
'max_favorites' => string '20' (length=2)
'max_favorites_spy' => string '10' (length=2)
'max_keeplog' => string '7' (length=1)
'max_keeprank' => string '30' (length=2)
'max_keepspyreport' => string '30' (length=2)
'max_spyreport' => string '10' (length=2)
'reason' => string '' (length=0)
'servername' => string 'Dream Local' (length=11)
'server_active' => string '1' (length=1)
'session_time' => string '180' (length=3)
'url_forum' => string 'http://ogsteam.fr/index.php' (length=27)
'log_phperror' => string '0' (length=1)
'block_ratio' => string '0' (length=1)
'ratio_limit' => string '0' (length=1)
'version' => string '3.05' (length=4)

les valeurs sont aussi colorés normalement ...
un autre exemple:


Vous pouvez changer certains paramètres :
xdebug.var_display_max_data= Change la longueur maximale des variables affichés par xdebug. la valeur par défaut est 512 caractères. Au delà, la variable sera coupée. Il y a bien sur une information quand cela arrive.

xdebug.var_display_max_children= Change le nombre maximum d'éléments de tableaux ou d'objets affichés. La valeur par défaut est 128

xdebug.var_display_max_depth= Change le nombre maximum d'éléments imbriqués affichés (nested level). Par défaut cette valeur est égale à 3


Xdebug permet aussi d'améliorer les messages d'erreurs en vous fournissant plus d'information et en les présentant de manière structurés:

Le message d'erreur, nous donne le type de problème (Undefined variable) dans quel fichier (local_vars.php) à quelle ligne (line 23)
mais aussi comment on est arrivé à ce script :
la fonction foo() à appelé la fonction bar() qui à son tour à appelé baz() ainsi que les n° de lignes à laquelle ces fonctions ont été appelé.
En plus, on a une indication du temps écoulé et la quantité de mémoire utilisé !!!

C'est déjà pas mal, mais on peux faire mieux

xdebug.show_local_vars=1 Permet d'afficher le contenu de TOUTE les variables locales dans le contexte du script.

Vraiment très utile en cas de problème, pour repérer une variable non initialisé par exemple

Un exemple typique des risques de sécurité ! Si vous regardez le screen-shot précédent, il y avait des variables qui contenaient un login et un password pour la base de données ....
Par contre, pour certains scripts, cela génére pas mal de texte en sortie, ce qui ralenti l'exécution et peu planté celui ci si le temps d'execution atteint la limite.
Le cas typique est celui de PhpMyAdmin qui génère des tonnes d'erreurs de Notice, ce qui plante l'import des bases de données même avec des fichiers de petites tailles qui passent sans soucis lorsque l'affichage des erreurs est désactivé

xdebug.dump_globals=On Permet d'afficher le contenu des variables globales dans les messages d'erreurs

xdebug.dump.= Spécifie quelle variable globale et quel paramètre(s) de celle-ci, on doit afficher.
peut être égal à GET, POST, SERVER, COOKIE, FILES, REQUEST, ou SESSION
exemple :
xdebug.dump.SERVER=HTTP_HOST, SERVER_NAME
xdebug.dump.GET=*
Le contenu des variables globales ne changeant pas durant l'exécution d'un script, si celui-ci provoque plusieurs erreurs, le contenu ne sera affiché qu'une seul fois !!


xdebug.collect_params= Permet de demander d'afficher les paramètres passer à la variable
0 = rien afficher
4 = afficher toutes les variables et leurs contenus complet

Un dernier paramètre fort utile, il peut arriver qu'un script parte dans une boucle infinie. Sous Linux, cela peux se terminer par un segfault, tandis que sous Windows cela peux carrément bloquer le système :o
Pour éviter cela xdebug permet de limiter le nombre maximum de récursion dans une boucle
xdebug.max_nesting_level= la valeur par défaut est 100
cependant ce paramètre n'est pas actif sur les boucles FOR/NEXT WHILE et autres dans le même genre !!

---------- Part 2 ----------

Je vais maintenant vous montrer une de ses plus grandes qualités :
La possibilité d'exécuter vos scripts PHP en pas à pas (relisez encore une fois, pour être bien sur d'avoir compris !)

1 - Environnement

Pour la suite des explications, je pense qu'il est nécessaire pour moi de préciser un peu ma configuration.
J'ai une machine de travail, avec Windows XP avec laquelle je surf et j'écris les scripts.

En plus j'ai un serveur Linux sous Debian/Elive.
Sur cette machine j'ai installé un package Lampp qui fournis, pré-configurer, un serveur web Apache, PHP 5 ou 4 au choix, MySQL 5, PhpMyAdmin et un serveur FTP (plus d'autres choses encore).
J'aurais pu tout installer manuellement avec les packages Debian, mais si tout existe en une seule archive, où il ne faut que décompresser, pourquoi se prendre la tête ?

Pour un serveur web de développement, vous n'avez pas besoin d'une machine hyper puissante (puisque par définition vous serez le seul dessus), seule la mémoire est importante (et encore !!!). Mon Linux tourne sur un AMD K7 à 800Mhz avec 400Mo de mémoire (et c'est déjà trop).
Chez certain revendeurs de matériel d'occasion, vous pouvez trouver des machines plus performante pour moins de 100? !! Alors pourquoi s'en priver.

Le répertoire htdocs de Apache est partagé par Samba et est mappé sur la machine XP avec tout les droits en lecture/écriture
Celui ci contient un sous-répertoire ogspy/ (en fait c'est ce répertoire qui est mappé sur la machine XP !! )

Le PC XP à comme adresse IP : 192.168.28.101
Le serveur Linux à comme adresse IP : 192.168.28.55
(j'ai beaucoup de machine dans mon réseau personnel , je ne parle ici que de celles utile à l'explication)

2 - Configuration

Pour commencer, il faut rajouter quelques lignes dans le fichier php.ini du serveur.
Dans la section [xdebug] que vous avez créer dans la première partie:

xdebug.remote_enable = true Cette ligne active le debugage à distance

xdebug.remote_mode = req Ce paramètre défini le type de debugage. Soit "req" ou request (demande), le "client" initie une session de debugage en envoyant un paramètre XDEBUG_SESSION_START par GET ou POST avec une valeur qui sera l'identifiant de la session.
Ou "jit" , qui démarrera une session de débugage dès qu'une erreur sera rencontrée.
Pour des soucis de simplicité, et de compatibilité avec le "client", nous utiliserons la méthode "req"

xdebug.remote_host = 192.168.28.101 Ce paramètre est plutôt simple à comprendre, il s'agit de l'adresse IP de la machine qui lancera le debugage.
Il est possible de mettre "localhost" si le serveur et le client sont sur la même machine.

xdebug.remote_port = 9000 Ceci est le port sur lequel le client doit "écouter" les messages de débuggages. Ce n° de port est standard, donc sauf pour d'excellente raisons, éviter de le changer

xdebug.remote_handler = dbgp C'est le type de protocole de debuggage utilisé. Vous avez le choix entre "php3", "gdb" et "dbgp". le dernier étant le plus récent et le plus "puissant, autant utilisé celui ci . Sauf si votre client en utilise un autre :rolleyes:

xdebug.remote_autostart = false Si vous mettez ce paramètre à "True", le serveur tentera de contacté le client à chaque execution d'un script pour le débugage

xdebug.remote_log = xdebuglog Ce paramètre permet de créer un fichier log des transactions entre le serveur et le client au cas ou vous auriez des soucis pour faire le fonctionner.

Pour que ces paramètres soient pris en compte, vous devez redémarrer le serveur Apache.

3 - Client

Maintenant, vous avez besoin d'un client pour piloter le serveur, démarrer les sessions et recevoir les infos.
Il en existe un petit paquet aussi bien sous Linux que sous Windows. Il existe même un add-on pour Firefox (pas compris comment il fonctionne !!). Malheureusement, beaucoup sont des logiciels commerciaux et dans les gratuits pour Windows, une bonne partie ne fonctionne pas ou n'accepte de fonctionner que si le serveur tourne sur la même machine :rolleyes:
Citons rapidement :
Notepad++ pour lequel un plugin existe
Netbeans un IDE (Environnement de développement Intégré) en Java qui supporte PHP depuis récemment
Eclipse un autre IDE en Java qui supporte assez bien le PHP.

Le seul que j'ai vraiment réussi à faire fonctionner de manière satisfaisante est Eclipse !!
Donc commencez, par le downloader et l'installer (attention: plus de 120Mo !!)

Ensuite lancez le ... c'est assez long au démarrage, heureusement cela va mieux une fois qu'il est chargé


L'interface de Eclipse pour PHP.

Ensuite, vous devez configurer Eclipse pour qu'il fonctionne avec xdebug.

On commence par lui dire d'utiliser le navigateur par défaut du systeme au lieu de celui interne :
Dans le menu "Window" -> "Preferences" -> "General" -> "Web Browser"

Choisissez le navigateur par défaut ou spécifiez "Firefox" pour être sur !!
Cliquez sur le bouton "Apply"

Puis allez dans les options de PHP.
Par défaut, Eclipse utilise le debuggeur de Zend (payant et cher !! Merci pour lui )
Toujours dans les préférences -> "PHP" -> "Debug"
Changez "Zend Debugger" par "Xdebug"

Cliquez sur "Apply"
Vous pouvez maintenant fermer l'écran des préférences.

Maintenant, il faut créer le projet OGSpy dans Eclipse.
Dans le menu "File" -> "New" -> "PHP Project"
(vous pouvez aussi cliquer sur le 1er icône de la barre, sur la flèche juste à coté, un menu apparaît et vous pouvez sélectionner "PHP Project" le premier de la liste)


Il n'y a pas grand chose à configurer.
Vous donnez un nom, et le répertoire mapper de votre serveur web
Puis cliquez sur "Finish" (la seconde page ne sert pas à grand chose)

Eclipse va parcourir l'ensemble des fichiers de votre serveur ogspy et remonter un certain nombre d'informations.
En particulier, il va remonter un certain nombre de ce qu'il considère comme des erreurs dans le code ... Je pense que le code d'analyse n'est pas des plus performant :rolleyes:

Maintenant, nous devons finir de configurer le debugger, et créer les paramètres de notre session de debuggage.

Dans le menu "Run" -> "Open Debug Dialog"

Cliquez d'abord sur "PHP Web page" puis sur le premier icône pour créer une nouvelle configuration
Donnez un nom à cette configuration, "OGSpy" par exemple
Vérifiez que le débugger est bien sur Xdebug
Pour le fichier, c'est par rapport à la racine du projet . Si vous cliquez sur le bouton "Browse" cela sera plus clair !!
Nous sommes obligé de spécifié le fichier "index.php" de la racine, parce que avec les protections de OGSpy, on ne peux pas accédé aux autres pages directement, mais rassurez vous cela n'est pas un soucis (de toute facon, il faut aussi initialiser les variables et établir la connexion à la base de données)
Si vous validez l'option suivante "Breakpoint" -> "Break at first line" : il s'arrêtera systématiquement à la première ligne de "index.php". A vous de voir à l'usage
L'URL est celui que vous tapez dans le navigateur, lorsque vous accédez à votre serveur.

Il nous reste plus qu'à définir le serveur en cliquant sur le bouton "New" qui est sur la ligne "PHP Server : Default PHP Server"

Vous ne changez pas le nom, simplement mettre l'URL dans la bonne case.
NB : Cet URL plus celui de la page précédente doivent fournir l'URL complet pour accéder à votre serveur OGSpy.

Allez sur le deuxième Onglet:

Ici il faut donner la correspondance entre les fichiers du serveur et ceux du projet ou sur le disque mapper. Je pense que seule la deuxième ligne sur le screen-shot est nécessaire

Sauvegardez le tout, c'est terminer pour la configuration

Ouf, ce fut long mais on va enfin pouvoir passer au fun

4 - Premier Debug

On va charger une page qu'on souhaite debugger. Par exemple et au hasard "attaques.php".

Maintenant on va créer un breakpoint, ou point d'arrêt, pour signaler au debugger qu'on souhaite s'arrêter à une ligne précise.
C'est très simple, il suffit de double-cliquer sur la ligne choisis. Ici j'ai pris la ligne 20
(vous pouvez aussi faire un click-droit sur la ligne et sélectionner "Toggle breakpoint" dans le menu contextuel)

Maintenant on clique sur l'affreux "bug" dans la barre et c'est parti (attachez votre ceinture)

Deux choses se passe en même temps:
1°) La page principal de OGspy se charge dans Firefox : Vous devriez arriver dans la page de login.
Remarquez l'URL dans la barre d'adresse de Firefox "XDEBUG_SESSION_START=ECLIPSE_DBGP&KEY=12088984795932"
2°) La vue dans Eclipse change et passe en mode "debug" !!

Maintenant, dans OGspy, vous vous loguez et vous naviguez jusqu'au module qui est sensé afficher la page que vous voulez debugger (le mod gestion des Attaques dans notre cas)

Quand vous arrivez dans la page, vous allez voir que le chargement s'interrompt puisqu'on à mis un breakpoint juste au début du fichier.

Eclipse, à ce moment, affiche le script, la liste de toutes les variables et leurs contenu et une tonne d'autres informations

C'est là que vous allez trouver que votre écran est trop petit même si vous avez un 21'' . C'est aussi dans ces moments, que 2 écrans prennent tout leur sens ...
Dans cet état, l'execution du script est bloqué et vous pouvez faire tout ce que vous voulez, même changer la valeur des variables
Ensuite, soit vous relancez l'exécution normale en cliquant sur le bouton vert (ou "F8") ou vous arrêtez complètement de script en cliquant sur le bouton rouge (ou "Ctrl+F2").
Ou mieux, vous avancez d'une ligne à la fois en pressant "F5" ou l'icône "Step Into" (la première flèche).

Les possibilités sont énormes et c'est sûrement bien plus efficace que des dizaines de "echo" et de "var_dump", surtout que cela n'implique pas de changer le code !!!


Ce sera tout pour aujourd'hui
Xdebug possède encore d'autres atouts comme les traces ou le profiling (permet d'analyser le déroulement des scripts pour optimisations), mais je vous renvois à la documentation ou à cet article fort bien fait et qui m'a permis d'installer et de configurer Xdebug la première fois

Have fun

ericc

Vous devez être identifié pour poster un commentaire sur ce site. Merci de vous identifier ou, si vous n'êtes pas enregistré, de cliquer ici pour vous inscrire.
Temps d'exécution:0.1537s, dont0.0154de celui des requêtes.Requêtes BdD:29. Utilisation mémoire:1,432ko