Xdebug

De Wiki de Jordan LE NUFF
Sauter à la navigation Sauter à la recherche

Présentation

Xdebug est une extension pour PHP facilitant le débogage et le développement. Il contient un débogueur fonctionnant clé-en-main avec les IDEs; il met à niveau la fonction var_dump() de PHP; il ajoute des traces de pile pour les notices, les avertissements, les erreurs et les exceptions; il comporte des fonctionnalités pour enregistrer chaque appel de fonction et chaque attribution de variable sur disque; il contient un profileur; et il fournit une fonctionnalité de couverture de code à utiliser avec PHPUnit.

Plus d'informations sur le site de l'éditeur :

Compatibilité PHP

Sur la page https://xdebug.org/docs/compat#versions de Xdebug, on peut y trouver un tableau de compatibilité.

En date du 13/10/2020, le tableau est le suivant :

ClipCapIt-201013-143448.PNG

Installation

Pour PHP 5

Télécharger la dernière version de Xdebug compatible avec la version 5 de PHP : 

wget https://xdebug.org/files/xdebug-2.5.5.tgz

Sur vmwebpic02, PHP 5 a été installé depuis les sources et elles sont disponibles dans le dossier /local/builds/php-5.6.40. De ce fait, les seuls prérequis à respecter sont automake et autoconf. Vérifier leur présence avec la commande suivante : 

rpm -qa|grep -E "automake|autoconf"

Exemple de retour : 

automake-1.16.1-4.1.noarch
autoconf-2.69-16.5.noarch

Décompresser Xdebug : 

tar -xvzf xdebug-2.5.5.tgz

Déplacer le dossier Xdebug précédemment décompressé dans le dossier /local/builds : 

mv xdebug-2.5.5 /local/builds/xdebug-2.5.5_for_php5

Se rendre dans le dossier et lancer phpize : 

cd /local/builds/xdebug-2.5.5_for_php5
phpize5

Exemple de retour : 

Configuring for:
PHP Api Version:         20131106
Zend Module Api No:      20131226
Zend Extension Api No:   220131226

Lancer la configuration de la compilation de l'extension Xdebug : 

./configure --with-php-config=/local/php/php5/bin/php-config

Exemple de fin de retour : 

...
configure: creating ./config.status
config.status: creating config.h

Lancer la compilation : 

make

Exemple de fin de retour : 

...
Build complete.
Don't forget to run 'make test'.

Copier l'extension fraîchement compilée vers le dossier d'extension de PHP 5 : 

cp modules/xdebug.so /local/php/php5/lib64/extensions/no-debug-non-zts-20131226/

Editer le fichier /local/php/php5/lib64/php.ini et y ajouter la ligne suivante : 

zend_extension = /local/php/php5/lib64/extensions/no-debug-non-zts-20131226/xdebug.so

Relancer PHP 5 : 

systemctl restart php5-fpm.service

Pour PHP 7

Obtenir les informations PHP

Se connecter en SSH sur le serveur désiré (par exemple : vmwebpic02) et lancer la commande suivante : 

php7 -i

Cela permet d'obtenir les informations relatives à l'instance de PHP utilisée. Les informations remontées sont les mêmes que celles obtenues au travers d'une page web avec un phpinfo();.

Aller sur le site Xdebug

Copier l'intégralité du retour obtenu, se rendre sur la page https://xdebug.org/wizard.php, coller les données copiées dans le cadre prévu à cet effet et cliquer sur Analyse my phpinfo() output.

Cela permet aux serveurs de Xdebug d'analyser la configuration actuelle de l'instance de PHP utilisée sur vmwebpic02 et de donner des directives personnalisées pour installer Xdebug.

En l'occurrence, voici le retour obtenu :

Summary
  • Xdebug installed: no
  • Server API: Command Line Interface
  • Windows: no
  • Zend Server: no
  • PHP Version: 7.3.4
  • Zend API nr: 320180731
  • PHP API nr: 20180731
  • Debug Build: no
  • Thread Safe Build: no
  • OPcache Loaded: no
  • Configuration File Path: /local/php/php7/lib64
  • Configuration File: /local/php/php7/lib64/php.ini
  • Extensions directory: /local/php/php7/lib64/extensions/no-debug-non-zts-20180731
Instructions
  1. Download xdebug-2.7.2.tgz
  2. Install the pre-requisites for compiling PHP extensions. These packages are often called 'php-dev', or 'php-devel', 'automake' and 'autoconf'.
  3. Unpack the downloaded file with tar -xvzf xdebug-2.7.2.tgz
  4. Run: cd xdebug-2.7.2
  5. Run: phpize (See the FAQ if you don't have phpize).
    As part of its output it should show:
    Configuring for:
...
Zend Module Api No:      20180731
Zend Extension Api No:   320180731
    If it does not, you are using the wrong phpize. Please follow this FAQ entry and skip the next step.
  6. Run: ./configure
  7. Run: make
  8. Run: cp modules/xdebug.so /local/php/php7/lib64/extensions/no-debug-non-zts-20180731
  9. Edit /local/php/php7/lib64/php.ini and add the line
zend_extension = /local/php/php7/lib64/extensions/no-debug-non-zts-20180731/xdebug.so

Suivre les instructions

Télécharger le paquet Xdebug proposé : 

wget http://xdebug.org/files/xdebug-2.7.2.tgz

Sur vmwebpic02, PHP 7 a été installé depuis les sources et elles sont disponibles dans le dossier /local/builds/php-7.3.4. De ce fait, les seuls prérequis à respecter sont automake et autoconf. Vérifier leur présence avec la commande suivante : 

rpm -qa|grep -E "automake|autoconf"

Exemple de retour : 

automake-1.16.1-4.1.noarch
autoconf-2.69-16.5.noarch

Décompresser Xdebug : 

tar -xvzf xdebug-2.7.2.tgz

Déplacer le dossier Xdebug précédemment décompressé dans le dossier /local/builds : 

mv xdebug-2.7.2 /local/builds/xdebug-2.7.2_for_php7

Se rendre dans le dossier et lancer phpize : 

cd /local/builds/xdebug-2.7.2_for_php7
phpize7

Exemple de retour : 

Configuring for:
PHP Api Version:         20180731
Zend Module Api No:      20180731
Zend Extension Api No:   320180731

Lancer la configuration de la compilation de l'extension Xdebug : 

./configure --with-php-config=/local/php/php7/bin/php-config

Exemple de fin de retour : 

...
configure: creating ./config.status
config.status: creating config.h

Lancer la compilation : 

make

Exemple de fin de retour : 

...
Build complete.
Don't forget to run 'make test'.

Copier l'extension fraîchement compilée vers le dossier d'extension de PHP 7 : 

cp modules/xdebug.so /local/php/php7/lib64/extensions/no-debug-non-zts-20180731

Editer le fichier /local/php/php7/lib64/php.ini et y ajouter la ligne suivante : 

zend_extension = /local/php/php7/lib64/extensions/no-debug-non-zts-20180731/xdebug.so

Relancer PHP 7 : 

systemctl restart php7-fpm.service

Configuration complémentaire

Un des intérêt de Xdebug est de pouvoir s'y connecter à distance depuis un IDE. Pour ce faire, ajouter les options suivantes dans le php.ini de l'instance PHP désirée : 

xdebug.remote_port=9000
xdebug.remote_enable=1
xdebug.idekey="PHPSTORM"

Pour les instances PHP embarquées en tant que module sous Apache, redémarrer Apache (le graceful restera sans effet). Pour les instances PHP lancées via PHP-FM, redémarrer PHP-FPM.

Directives de configuration

D'après la documentation officielle sur les différents paramètres de Xdebug, voici ce que devrait contenir le fichier de configuration de PHP (php.ini) : 

[xdebug]
zend_extension="xdebug.so"
; Go to https://xdebug.org/docs/all_settings for more informations
;xdebug.auto_trace = false
;xdebug.cli_color = 0
;xdebug.collect_assignments = false
;xdebug.collect_includes = true
;xdebug.collect_params = 0
;xdebug.collect_return = false
;xdebug.collect_vars = false
;xdebug.coverage_enable = true
;xdebug.default_enable = true
;xdebug.dump.COOKIE = ""
;xdebug.dump.FILES = ""
;xdebug.dump.GET = ""
;xdebug.dump.POST = ""
;xdebug.dump.REQUEST = ""
;xdebug.dump.SERVER = ""
;xdebug.dump.SESSION = ""
;xdebug.dump_globals = true
;xdebug.dump_once = true
;xdebug.dump_undefined = false
;xdebug.extended_info = 1
;xdebug.file_link_format =
;xdebug.filename_format = ...%s%n
;xdebug.force_display_errors = 0
;xdebug.force_error_reporting = 0
;xdebug.gc_stats_enable = false
;xdebug.gc_stats_output_dir = /tmp
;xdebug.gc_stats_output_name = gcstats.%p
;xdebug.halt_level = 0
;xdebug.idekey = *complex*
;xdebug.manual_url = http://www.php.net
;xdebug.max_nesting_level = 256
;xdebug.max_stack_frames = -1
;xdebug.overload_var_dump = 2
;xdebug.profiler_aggregate = 0
;xdebug.profiler_append = 0
;xdebug.profiler_enable = 0
;xdebug.profiler_enable_trigger = 0
;xdebug.profiler_enable_trigger_value = ""
;xdebug.profiler_output_dir = /tmp
;xdebug.profiler_output_name = cachegrind.out.%p
;xdebug.remote_addr_header = ""
;xdebug.remote_autostart = false
;xdebug.remote_connect_back = false
;xdebug.remote_cookie_expire_time = 3600
;xdebug.remote_enable = false
;xdebug.remote_handler = dbgp
;xdebug.remote_host = localhost
;xdebug.remote_log =
;xdebug.remote_log_level = 7
;xdebug.remote_mode = req
;xdebug.remote_port = 9000
;xdebug.remote_timeout = 200
;xdebug.scream = false
;xdebug.show_error_trace = 0
;xdebug.show_exception_trace = 0
;xdebug.show_local_vars = 0
;xdebug.show_mem_delta = 0
;xdebug.trace_enable_trigger = false
;xdebug.trace_enable_trigger_value = ""
;xdebug.trace_format = 0
;xdebug.trace_options = 0
;xdebug.trace_output_dir = /tmp
;xdebug.trace_output_name = trace.%c
;xdebug.var_display_max_children = 128
;xdebug.var_display_max_data = 512
;xdebug.var_display_max_depth = 3

DBGp Proxy Tool

Cet outil permet d'agir comme un proxy et de faire suivre la requête de débogage vers les IDE en fonction de la clé IDE utilisée. Ainsi, plusieurs développeurs peuvent utiliser Xdebug sur une même instance de PHP.

Principe de fonctionnement

L'extension PHP Xdebug se connectera sur le port 9000 du proxy, et les utilisateurs se connecteront sur le port 9001 du proxy.

Le proxy étant installé sur le même serveur que PHP, l'écoute du proxy pour l'extension PHP Xdebug se fera sur l'adresse locale du serveur : 127.0.0.1

En revanche, les utilisateurs se connectant depuis leurs postes respectifs, l'écoute du proxy pour leurs IDEs se fera sur l'adresse IP "publique" du serveur. Pour une configuration simple et générale, l'adresse 0.0.0.0 est suffisante.

Installation du binaire dbgpproxy

Créer le dossier où sera localisé le binaire dbgpproxy : 

mkdir /local/dbgpproxy

Récupérer le binaire dbgpproxy depuis le site de Xdebug : 

wget https://xdebug.org/files/binaries/dbgpProxy -O /local/dbgpproxy/dbgpproxy

Autoriser le binaire dbgpproxy à être exécuter : 

chmod u+x /local/dbgpproxy/dbgpproxy

Création du service dbgpproxy

Créer un fichier /usr/lib/systemd/system/dbgpproxy.service et y insérer le contenu suivant : 

[Unit]
Description=dbgpproxy
After=network.target

[Service]
Type=simple
User=root
Group=root
WorkingDirectory=/local/dbgpproxy
ExecStart=/local/dbgpproxy/dbgpproxy -i 0.0.0.0:9001 -s 127.0.0.1:9000
KillSignal=SIGINT
RemainAfterExit=no
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

Prise en compte du nouveau service : 

systemctl daemon-reload

Démarrage du service dbgpproxy.service : 

systemctl start dbgpproxy.service

Activation du serveur dbgpproxy.service au démarrage du serveur : 

systemctl enable dbgpproxy.service

Affichage de l'état du service dbgpproxy.service : 

systemctl status dbgpproxy.service

Exemple de retour :

Putty icon.png Console SSH
[root@myserver ~]# systemctl status dbgpproxy.service
● dbgpproxy.service - dbgpproxy
   Loaded: loaded (/usr/lib/systemd/system/dbgpproxy.service; enabled; vendor preset: disabled)
   Active: active (running) since mar. 2020-11-03 17:27:58 CET; 7s ago
 Main PID: 4823 (dbgpproxy)
   CGroup: /system.slice/dbgpproxy.service
           └─4823 /local/dbgpproxy/dbgpproxy -i 0.0.0.0:9001 -s 127.0.0.1:9000

nov. 03 17:27:58 myserver.local systemd[1]: Started dbgpproxy.
nov. 03 17:27:58 myserver.local dbgpproxy[4823]: Xdebug DBGp proxy (0.3)
nov. 03 17:27:58 myserver.local dbgpproxy[4823]: Copyright 2020 by Derick Rethans
nov. 03 17:27:58 myserver.local dbgpproxy[4823]: 16:27:58.875 [warn] [SSL] The 'certs/fullchain.pem' file could not be found, not enabling SSL listeners
nov. 03 17:27:58 myserver.local dbgpproxy[4823]: 16:27:58.876 [info] [dbgpProxy] Proxy started
nov. 03 17:27:58 myserver.local dbgpproxy[4823]: 16:27:58.876 [info] [server] Started server server on 127.0.0.1:9000
nov. 03 17:27:58 myserver.local dbgpproxy[4823]: 16:27:58.876 [info] [server] Started client server on 0.0.0.0:9001

Vérification des ports en écoute : 

netstat -paunt|grep -E "9000|9001"

Exemple de retour :

Putty icon.png Console SSH
[root@myserver ~]# netstat -paunt|grep -E "9000|9001"
tcp        0      0 127.0.0.1:9000          0.0.0.0:*               LISTEN      21552/dbgpproxy
tcp        0      0 172.17.0.221:9001       0.0.0.0:*               LISTEN      21552/dbgpproxy

Ouverture du port dans le pare-feu

Seul le port 9001 devant être accessible depuis l'extérieur, passer les commandes suivantes pour l'autoriser dans le pare-feu : 

firewall-cmd --add-port=9001/tcp
firewall-cmd --add-port=9001/tcp --permanent

Modification des paramètres PHP

Mettre à jour de certaines directives de configuration pour un début de fonctionnement (en l'occurrence, juste xdebug.remote_enable ici) : 

...
[xdebug]
...
;xdebug.remote_enable = false
xdebug.remote_enable = true
;xdebug.remote_handler = dbgp
...

Relancer Apache ou PHP-FPM pour prise en compte des modifications : 

httpd -k graceful

ou 

systemctl restart php7-fpm.service
Récupérée de « https://wiki.jordan-lenuff.com/index.php?title=Technique/PHP/Xdebug&oldid=834 »