Configuration de Xdebug dans PHPStorm

Le débogage est l'un des processus les plus importants de la programmation. Avec l'aide d'un débogueur, vous pouvez voir ce qui se passe dans le programme, quelles fonctions sont exécutées, ce qui est stocké dans les variables, ainsi que tout exécuter étape par étape et comprendre exactement à quelle ligne et à quelle valeur des variables une erreur se produit.

Par exemple, le débogueur Xdebug est utilisé pour PHP, PHPStorm est l'un des environnements de développement les plus populaires. Voyons maintenant comment configurer Xdebug dans PhpStorm pour le débogage sur l'ordinateur local et dans Docker.

Configurer XDEBUG dans PHPSTORM

Voyons comment le débogage est effectué sur le serveur local.

Nous allons examiner l'ensemble du processus en utilisant Ubuntu et l'interpréteur PHP configuré avec Apache comme exemple. Pour d'autres configurations, les chemins d'accès aux fichiers peuvent être différents, mais l'essentiel ne change pas. Le débogueur Xdebug permet de mettre en pause l'exécution du code, de visualiser la pile d'appels et le contenu des variables. Son seul inconvénient est qu'il n'y a pas d'interface de contrôle pratique. Les IDE sont généralement utilisés pour gérer le débogage. Mais l'IDE ne peut pas dire au débogueur de commencer le débogage car il n'est responsable que du code. Pour cela, vous aurez besoin de l'extension de navigateur Debug Helper, avec l'aide de laquelle vous pouvez activer le mode de débogage.

Vous devez d'abord installer Xdebug. Pour ce faire, exécutez :

$ sudo apt install xdebug

Une fois le processus d'installation de Xdebug terminé, vous devez configurer le programme de manière à ce que, lorsque vous démarrez une session de débogage, il tente de se connecter à notre IDE pour contrôler le débogage. Pour ce faire, ajoutez ces lignes au fichier /etc/php/7.4/apache2/conf.d/20-xdebug.ini dans la version Xdebug 2 :

$ sudo vi /etc/php/7.4/apache2/conf.d/20-xdebug.ini
zend_extension=xdebug.so
xdebug.remote_enable=1
xdebug.remote_host=127.0.0.1
xdebug.remote_connect_back=1
xdebug.remote_port=9000
xdebug.remote_handler=dbgp
xdebug.remote_mode=req
xdebug.remote_autostart=false

Pour une version plus récente, il est préférable d'utiliser un format différent :

xdebug.mode=debug
xdebug.start_with_request=trigger
xdebug.discover_client_host = false
xdebug.client_host = 127.0.0.1
xdebug.client_port = 9000

Examinons les paramètres de plus près. Le premier paramètre xdebug.mode - mode de débogage, les options possibles sont :

• develop - active la sortie d'informations supplémentaires, remplace var_dump ;

• debug - mode d'exécution du code ligne par ligne, c'est le mode dont nous avons besoin dans ce cas ;

• profile - profilage ;

• trace -traçage de l'exécution du programme.

Plusieurs modes sont activés simultanément lorsqu'ils sont énumérés entre virgules. La deuxième ligne xdebug.start_with_request définit comment le débogueur sera lancé pour les modes debug, trace et similaires :

• yes - toujours, lors de l'exécution de scripts php ;
• no - démarrage uniquement à partir du code en utilisant des fonctions spéciales ;
• trigger - sur demande, en utilisant une variable spéciale dans $_ENV, $_POST, $COOKIE ou un autre tableau. Cette option convient le mieux dans ce cas, afin que le débogueur ne s'exécute pas lorsqu'il n'est pas nécessaire.

La troisième option xdebug.discover_client_host est fixée à true, auquel cas xdebug tente de se connecter à l'hôte passé dans l'en-tête HTTP_X_FORWARDED_FOR. Puisque l'hôte est spécifié à la ligne suivante, cette fonctionnalité n'est pas nécessaire dans ce cas. Ensuite, l'hôte client auquel se connecter pour le contrôle du débogage est 127.0.0.1 et le port 9000. C'est le port par défaut utilisé dans PhpStorm pour le moment. Après avoir sauvegardé les paramètres, vous devez redémarrer Apache à l'aide d'une commande spéciale :

$ sudo systemctl restart apache2

Ensuite, vous devez configurer PhpStorm. Lancez le programme, puis ouvrez le menu Run -> Edit Configurations. Vous verrez une fenêtre dans laquelle vous devez configurer le débogueur.

Cliquez sur le bouton + et sélectionnez PHP Remote Debugger dans la liste qui s'ouvre :

Ne modifiez rien dans les paramètres, indiquez simplement le nom de cette méthode de débogage. Si vous n'indiquez pas le serveur à partir duquel les connexions seront attendues, toutes les connexions seront acceptées.

Si vous souhaitez modifier le port auquel Xdebug se connectera, ouvrez File -> Settings -> PHP -> Debug -> DBGp Proxy. Ici, vous pouvez spécifier le port désiré.

Nous pouvons dire que l'IDE est maintenant prêt. Cliquez maintenant sur le bug dans la barre d'outils supérieure. Le programme commencera à attendre que le débogueur se connecte et nous placerons quelques points d'arrêt dans le code en cliquant simplement devant la ligne contenant le code :

Il ne reste plus qu'à configurer le navigateur.Pour Chrome, vous pouvez télécharger une extension spéciale. Installez-la et ouvrez la page que vous souhaitez déboguer. Cliquez sur l'icône de l'extension et sélectionnez Debug. L'icône de l'extension devient verte :

Actualisez la page et revenez à PHPStorm. Si tout a été fait correctement, une session de débogage démarrera. Lors de la première exécution, le programme peut vous demander de configurer les chemins d'accès aux fichiers locaux pour qu'ils correspondent aux chemins d'accès aux fichiers distants. Pour le serveur local, vous n'avez pas besoin de configurer quoi que ce soit ici, cliquez simplement sur Accepter :

Ensuite, le débogueur arrêtera l'exécution au point d'arrêt sélectionné et l'interface de débogage apparaîtra dans le programme :

Voyons maintenant comment configurer Xdebug PhpStorm et Docker.

Déboguer PHP dans DOCKER

Docker peut être un peu délicat. Puisque le débogueur doit se connecter à l'IDE lui-même, vous devez transmettre l'hôte au conteneur. Sous Windows, cela peut être fait en utilisant l'adresse host.docker.internal. Mais sous Linux, cela ne se fait pas par défaut. Pour ajouter une telle adresse, vous devez ajouter les lignes suivantes à docker-compose :

extra_hosts :

host.docker.internal : host-gateway

Nous utilisons la structure de répertoire suivante :

Le fichier docker-compose.yaml minimum requis ressemblera à ceci :

version: '3.5'
networks:
  losst-network:
services:
  nginx:
    image: nginx
    ports:
        - '8094:80'
    volumes:
        - ./www/:/var/www/
        - ./conf/nginx:/etc/nginx/conf.d
    networks:
        - losst-network
  php-fpm:
    build: 
      context: ./conf/php-fpm
    extra_hosts:
      host.docker.internal: host-gateway
    volumes:
      - ./www:/var/www/
    networks:
      - losst-network

Nous déclarons simplement deux conteneurs, nginx et php-fpm. Nous n'apportons aucune modification au premier, nous pouvons donc simplement prendre l'image officielle, monter le dossier source, le fichier de configuration et le port forward. Dans le second conteneur, il est nécessaire d'installer et de configurer Xdebug, qui devra donc être construit sur la base du conteneur php officiel. Pour ce même conteneur, il est nécessaire de spécifier la directive extra_hosts, sans laquelle rien ne fonctionnera. La configuration de Nginx est également assez standard :

server {
  listen 80;
  server_name _ !default;
  root /var/www/;
  add_header X-Frame-Options "SAMEORIGIN";
  add_header X-XSS-Protection "1; mode=block";
  add_header X-Content-Type-Options "nosniff";
  index index.html index.htm index.php;
  charset utf-8;
  location / {
    try_files $uri $uri/ /index.php?$query_string;
  }
  error_page 404 /index.php;
  location ~ .php$ {
    fastcgi_pass php-fpm:9000;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
    include fastcgi_params;
  }
}

C'est ainsi que vous configurez le traitement des scripts PHP dans le conteneur php-fpm, et que vous redirigez les URL inexistantes vers index.php, ce qui est tout à fait standard pour de nombreux frameworks et CMS. Dans le fichier Docker du conteneur php-fpm, cela ressemble à ceci :

Installer xdebug en utilisant pecl, puis copier son fichier de configuration dans le conteneur. Fichier :

xdebug.mode=debug
xdebug.start_with_request=trigger
xdebug.discover_client_host = false
xdebug.client_host = host.docker.internal
xdebug.client_port = 9000

Xdebug 3 pour PHP 8 est installé dans le conteneur, car l'ancienne version ne fonctionne plus avec cette version du langage, et la nouvelle syntaxe de configuration est donc utilisée. Well host, host.docker.internal, qui était auparavant prescrit dans docker-compose.yaml. La configuration de xdebug PHPStorm docker est maintenant terminée. Ensuite, vous pouvez exécuter le projet :

docker-compose up --build

Maintenant, comme dans l'option précédente, vous pouvez activer le mode debug dans le navigateur, rafraîchir la page et le debugger se connectera avec succès à l'IDE, malgré le fait qu'il tourne dans Docker