Xdebug est une extension PHP conçue pour le débogage et le profilage des applications PHP.
Développée par Derick Rethans, elle offre des fonctionnalités avancées pour comprendre et diagnostiquer les problèmes dans le code PHP.
Sa première version date de 2002. Elle est écrite en langage C (le langage utilisé pour développer des extensions PHP) et son code est open source sur GitHub : https://github.com/xdebug/xdebug.

Comment l’installer :

Cela va dépendre du système d’exploitation que l’on utilise.
Sur Windows, il existe des fichiers .dll prêts à l’emploi que l’on peut directement télécharger depuis le site officiel : https://xdebug.org/download.
Il faudra ensuite placer ce fichier dans le répertoire des extensions de PHP.

Note : suivant votre configuration Windows pour effectuer du développement, il se peut que le dossier des extensions se trouve à des emplacements différents, notamment avec des environnements de développement tout-en-un comme WampServer ou Laragon.
D’ailleurs, avec WampServer, l’extension Xdebug est intégrée par défaut. Il faudra ensuite redémarrer votre environnement de développement.

Installer Xdebug sous un système linux :

Sur une installation sous Linux, Xdebug peut être installé via APT ou le gestionnaire de paquets PECL (un gestionnaire de paquets pour PHP).

i vous avez besoin d’une version spécifique de Xdebug, vous pouvez l’obtenir en la recherchant dans les dépôts de votre distribution (par exemple, sous Debian et ses dérivés).

Alternative : Compilation depuis les sources

Dans de rares cas, ou pour des besoins particuliers, il est également possible de compiler l’extension directement depuis les sources.

Problème à l’installation :

Si vous rencontrez des problèmes lors de l’installation, que vous ne savez pas quelle version choisir, ou si vous hésitez entre une version Thread Safe (TS) ou Non Thread Safe (NTS), cela dépend de la façon dont PHP est exécuté : en tant que module Apache, en mode PHP-FPM ou en CLI.
Le site officiel de Xdebug propose un assistant d’installation : https://xdebug.org/wizard,
Il vous suffit d’y copier le contenu de votre phpinfo(), et il vous indiquera la version à installer.

Fichier de configuration de Xdebug

Encore une fois, cela va dépendre de votre système d’exploitation et de votre environnement de développement.
Dans cet exemple, nous allons utiliser un système Linux (Ubuntu), mais la configuration sera la même : il faudra simplement adapter les chemins des fichiers de configuration.

La configuration peut se faire à plusieurs endroits (comme pour toute extension PHP). La première solution consiste à effectuer la configuration dans le fichier php.ini.
Cependant, PHP dispose d’un dossier spécifique pour la configuration de ses extensions, et il est recommandé de l’utiliser.

Lors de l’installation, un fichier de configuration a été automatiquement créé. Pour l’instant, il permet uniquement de charger l’extension dans le moteur PHP.

Activer ou désactiver facilement l’extension Xdebug :

Pour activer ou désactiver un module PHP, y compris un module comme Xdebug, vous pouvez utiliser les commandes suivantes, qui permettent d’activer ou de désactiver un module PHP comme Xdebug.

Paramètre de configuration de Xdebug :

Xdebug possède un grand nombre de paramètres de configuration.
Nous allons passer en revue uniquement les principaux et les plus importants.
Cependant, la documentation officielle regroupe l’ensemble des paramètres et leur fonction associée :
https://xdebug.org/docs/all_settings.

Attention : si vous avez et utilisez plusieurs versions de PHP sur votre système, la configuration devra être effectuée pour chacune d’entre elles.
De même, si vous utilisez PHP dans différents modes (FPM ou CLI), il faudra configurer Xdebug pour ces deux modes de fonctionnement.

Xdebug est une extension PHP très complète, offrant plusieurs modes et fonctionnalités pour faciliter le développement, le débogage et l’optimisation des applications PHP.
Voici un tour d’horizon des principales fonctionnalités et des modes associés :

(debug, develop, trace, profile, etc.)
Vous pouvez choisir d’activer tous ces modes ou seulement certains d’entre eux dans la configuration de Xdebug.

XDebug avec le mode debug :

Xdebug modifie la fonction intégrée de PHP var_dump() pour l’afficher au format HTML.
Elle fournit des informations structurées sur une ou plusieurs expressions, incluant leur type et leur valeur. Les tableaux sont explorés récursivement, avec toutes leurs valeurs.

À noter que Xdebug dispose également d’une fonction nommée xdebug_var_dump(), qui effectue la même opération que la surcharge de la fonction var_dump() intégrée de PHP.

En mode develop, Xdebug affiche automatiquement une stack trace détaillée à chaque erreur ou exception, ce qui permet d’identifier rapidement la chaîne d’appels ayant mené à l’erreur.
Elle indique l’emplacement dans le code et l’ordre des appels, facilitant ainsi le diagnostic.

Si l’on analyse le code source, on remarque que Xdebug formate automatiquement la sortie avec des tableaux HTML.

ans le mode debug de Xdebug, voici comment l’erreur est affichée :

Fonctionnement général du mode Debug :

Le serveur web (Nginx ou Apache) reçoit la requête et la transmet à PHP-FPM (ou au module PHP d’Apache).
PHP exécute alors le script.
En temps normal, PHP exécute simplement le code et renvoie la réponse. Mais avec Xdebug activé, le processus est modifié.

Xdebug intercepte l’exécution dès le début du script en injectant un hook dans le moteur Zend (Zend Engine).
Il vérifie alors si une session de débogage doit être démarrée, selon la configuration (start_with_request=yes ou déclenchement par trigger).

Connexion avec l’IDE

S’il doit démarrer une session, Xdebug tente de se connecter à l’IDE (PhpStorm, VSCode, etc.) via le protocole DBGp.
Si l’IDE écoute sur le port défini (par défaut 9003 avec Xdebug 3), il prend le contrôle de l’exécution du script PHP.

L’IDE peut alors :

• Interrompre l’exécution si un point d’arrêt (breakpoint) est défini
• Afficher les variables et la pile d’appels (stack trace)
• Permettre une exécution pas à pas du code

XDebug avec le mode debug :

• Placer des points d’arrêt (breakpoints) dans votre code, c’est-à-dire des lignes où l’exécution du script s’arrêtera automatiquement pour inspection.
• Exécuter le code ligne par ligne (pas à pas), ce qui permet de suivre précisément le cheminement de l’exécution et de comprendre l’état des variables à chaque étape.
• Inspecter et modifier la valeur des variables en temps réel pendant l’exécution du script.
• Visualiser la pile d’appels (stack trace), c’est-à-dire la liste des fonctions ou méthodes appelées jusqu’au point d’arrêt.

Cela permet :

• De gagner un temps précieux dans la recherche et la correction de bugs complexes.
• D’éviter l’utilisation répétée de var_dump() ou die(), rendant le processus plus propre et professionnel.
• D’améliorer la compréhension du flux d’exécution et de l’état des variables à chaque étape.

Fonctionnement avec son IDE :

Le mode debug fonctionne de pair avec l’utilisation d’un IDE. La configuration varie selon l’IDE utilisé.
Prenons ici l’exemple de VSCode, mais cela fonctionnerait tout aussi bien avec PhpStorm ou un autre éditeur.

1. Téléchargez l’extension officielle depuis le store des extensions de VSCode :
   https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug
2. Allez dans la section Run and Debug (icône en forme de lecture avec un insecte à gauche, ou via le raccourci Ctrl+Shift+D).
3. Cliquez sur “Create a launch.json file” puis choisissez PHP.

Un fichier .vscode/launch.json sera alors créé avec une configuration par défaut.

Exemple :

Le paramètre xdebugSettings dans la configuration launch.json de Visual Studio Code permet de contrôler la quantité et la profondeur des données que Xdebug renvoie à l’IDE lors du débogage.
Ces réglages influencent la manière dont les variables (tableaux, objets, chaînes de caractères) sont affichées et explorées dans le panneau de débogage de VS Code.

Paramètre max_children

• Définition : Nombre maximum d’enfants (éléments) d’un tableau ou d’un objet que Xdebug renvoie lors de l’inspection d’une variable.
• Utilité : Limite le nombre d’éléments affichés dans l’IDE afin d’éviter de surcharger l’interface lorsqu’une variable contient un grand nombre d’éléments.
• Exemple : Avec max_children: 128, seuls les 128 premiers éléments d’un tableau ou objet seront affichés dans l’inspecteur de variables de VS Code.

---

Paramètre max_data

• Définition : Taille maximale (en octets) des chaînes de caractères renvoyées lors de l’inspection d’une variable.
• Utilité : Évite que de très longues chaînes (comme du texte brut ou du JSON volumineux) ne soient tronquées dans l’interface de débogage.
• Valeur spéciale : 1 signifie pas de limite — la chaîne complète sera affichée sans troncature.

---

Paramètre max_depth

Exemple : Avec max_depth: 3, Xdebug affichera les sous-éléments jusqu’à trois niveaux d’imbrication. Au-delà, l’exploration s’arrête.

Définition : Profondeur maximale d’exploration dans les structures imbriquées (tableaux ou objets).

Utilité : Contrôle jusqu’à quel niveau Xdebug va explorer et afficher les sous-éléments d’une variable complexe.

Démarrage de la session de débogage :

Vous pouvez utiliser le raccourci F5, passer par le menu Exécuter, ou cliquer sur le triangle vert pour lancer le débogage.
À ce stade, l’IDE attend la connexion du serveur.

La connexion peut se faire via :

• une requête du navigateur (le cas le plus courant),
• une requête curl,
• ou des outils comme Postman ou Insomnia, notamment pour tester une API.

Lorsque le script atteint un point d’arrêt, son exécution s’interrompt.
VS Code affiche alors la barre d’outils de débogage et met en surbrillance la ligne courante. Vous pouvez alors :

• Inspecter les variables et leur état à ce moment précis,
• Consulter la pile d’appels (stack trace) pour comprendre le chemin d’exécution,
• Modifier temporairement des valeurs si nécessaire, etc.

---

Contrôles de débogage

Arrêter (Stop / Shift+F5) : Termine la session de débogage.

Pas à pas (Step Over / F10) : Exécute la ligne courante et passe à la suivante, sans entrer dans les fonctions appelées.

Entrer dans (Step Into / F11) : Entre dans la fonction appelée pour la déboguer ligne par ligne.

Sortir (Step Out / Shift+F11) : Exécute le reste de la fonction actuelle et revient au niveau supérieur (appelant).

Continuer (Continue / F5) : Reprend l’exécution jusqu’au prochain point d’arrêt ou la fin du script.

Pause : Suspend l’exécution à tout moment.

Arrêter (Stop / Shift+F5) : Termine la session de débogage.

Plusieurs méthodes pour activer ou désactiver le mode Debug :

Il existe plusieurs façons de lancer une session de débogage :

• soit de manière automatique pour toutes les requêtes,
• soit à l’aide d’un déclencheur (paramètre dans une requête GET, POST ou via un cookie),
• ou encore via une fonction spécifique de Xdebug

XDEBUG_MODE=debug : active la session de débogage pour toutes les requêtes

En configurant xdebug.start_with_request=yes dans le fichier de configuration, Xdebug démarre automatiquement une session de débogage pour toutes les requêtes, sans déclencheur particulier, que ce soit via un navigateur, curl, Postman ou en CLI.
Aucun paramètre ou cookie spécifique n’est nécessaire.

✅ Idéal en développement local

Il suffit de lancer son IDE en mode écoute, puis d’exécuter le script : le débogage s’active automatiquement. Cela accélère le workflow et évite les oublis de déclencheur.

❌ À éviter absolument en production

Xdebug ralentit significativement l’exécution de chaque requête PHP, même si aucun point d’arrêt n’est atteint ou si l’IDE n’est pas en écoute.
Cela peut rendre le développement très lent, en particulier sur des projets volumineux ou des frameworks complexes.

Ce ralentissement s’explique par le fait que Xdebug, en mode debug, s’insère dans le cycle d’exécution de chaque requête PHP. Il modifie le comportement du moteur pour surveiller, tracer et collecter des informations utiles au débogage, ce qui génère un overhead de performance estimé entre 20 et 30 % sur l’exécution des scripts PHP.

XDEBUG_TRIGGER : Déclenchement manuel d’une session de débogage pour une requête spécifique

Avec cette configuration, Xdebug ne démarre une session de débogage que lorsque le déclencheur (trigger) est explicitement fourni.

Le nom du déclencheur par défaut est XDEBUG_TRIGGER.
Xdebug vérifie sa présence dans les superglobales $_ENV (variables d’environnement), $_GET, $_POST, ou $_COOKIE.

Supposons que vous ayez un fichier PHP accessible via l’URL suivante, par exemple : test.php.
Pour activer le débogueur, il suffit d’ajouter un paramètre HTTP (GET ou POST) à l’URL ou au corps de la requête.

Dans ce cas, dès que le trigger est présent dans la requête, Xdebug initie une session de débogage et tente de se connecter à votre IDE.

XDEBUG_TRIGGER : personnalisation du déclencheur de session

Vous pouvez choisir n’importe quelle valeur pour ce paramètre. Ce nom est utilisé pour identifier la session de débogage.

Si l’option xdebug.trigger_value est définie dans la configuration de Xdebug, alors la valeur fournie via XDEBUG_TRIGGER doit correspondre exactement à celle définie pour que le débogage soit activé.

Depuis Xdebug 3.1, il est possible de spécifier plusieurs valeurs via une liste séparée par des virgules.
Dans ce cas, Xdebug déclenchera une session de débogage si la valeur transmise correspond à l’une des valeurs configurées via xdebug.trigger_value.

XDEBUG_SESSION : Déclenchement manuel d’une session uniquement pour le débogage

XDEBUG_TRIGGER fonctionne quel que soit le mode activé dans Xdebug (profilage, débogage, trace, etc.).
Cependant, si l’on souhaite déclencher uniquement une fonctionnalité spécifique, il est possible d’utiliser des déclencheurs hérités dédiés à chaque mode.

Par exemple :

• XDEBUG_SESSION : pour activer uniquement le mode débogage par étapes (step debugging)
• XDEBUG_PROFILE : pour activer uniquement le profilage des performances
• XDEBUG_TRACE : pour activer uniquement la trace d’exécution (fonctionnelle)

Ces déclencheurs permettent un contrôle plus précis de quelle fonctionnalité de Xdebug est activée, sans passer par la configuration globale des modes.

XDEBUG_SESSION_START : sessions de débogage persistantes via cookies

Si vous souhaitez déboguer plusieurs requêtes HTTP consécutives (par exemple, pour suivre un processus ou une navigation dans une application), Xdebug peut utiliser un cookie pour maintenir une session de débogage active.
Vous pouvez passer n’importe quelle valeur à XDEBUG_SESSION_START, sauf si vous avez configuré une valeur spécifique dans xdebug.trigger_value.
Fonctionne indépendamment de xdebug.start_with_request.
Cela indique à Xdebug de démarrer une session de débogage et de définir un cookie nommé XDEBUG_SESSION.

Durée de vie du Cookie : Avant Xdebug 3.1 : Le cookie avait une durée de vie par défaut
d’une heure.
À partir de Xdebug 3.1 : Le cookie n’a pas de durée d’expiration par défaut. Cela signifie
qu’il restera actif jusqu’à ce qu’il soit explicitement supprimé ou que le navigateur soit fermé
(selon le comportement du navigateur).

XDEBUG_SESSION_STOP : Arrêter une session de débogage

Pour arrêter une session de débogage et supprimer le cookie XDEBUG_SESSION, vous pouvez envoyer le paramètre suivant dans une requête HTTP (GET ou POST) :

Utiliser l’extension de navigateur Xdebug :

L’extension permet d’activer ou de désactiver le débogage en un clic, sans avoir à modifier manuellement les URL ou à ajouter des paramètres GET/POST.
Vous n’avez pas besoin de modifier chaque requête individuellement pour ajouter des paramètres comme XDEBUG_SESSION_START.

https://chromewebstore.google.com/detail/xdebug-helper-byjetbrain/aoelhdemabeimdhedkidlnbkfhnhgnhm
https://addons.mozilla.org/en-GB/firefox/addon/xdebug-helper-by-jetbrains/

Sélectionnez l’option pour activer le débogage (généralement appelée “Debug”).
Lorsque l’on active le mode Debug, l’extension injecte automatiquement un cookie nommé XDEBUG_SESSION avec une valeur spécifique (par exemple PHPSTORM ou start) dans le navigateur.

Ce cookie est envoyé avec chaque requête HTTP effectuée par le navigateur.
Lorsque le serveur reçoit une requête contenant ce cookie, Xdebug est déclenché et démarre une session de débogage.
Lorsque l’on désactive le débogage, l’extension supprime automatiquement le cookie.

Cette extension n’est pas obligatoire, elle permet simplement de se simplifier la vie en injectant directement un cookie HTTP dans le navigateur.
Comme XDEBUG_SESSION_START, le nom du cookie est important si xdebug.trigger_value est défini. Dans ce cas, la valeur du cookie doit être identique à celle définie dans trigger_value.

Note on pourrait également définir un cookies en Javascript de cette façon

Résumé des paramètres HTTP utilisés :

Paramètres	Action
XDEBUG_TRIGGER=session_name	Démarre une session de débogage pour une seule requête.
XDEBUG_SESSION=session_name	Alias de XDEBUG_TRIGGER dans le cas du débogage
DEBUG_SESSION_START=session_name	Démarre une session de débogage persistante et définit un cookie.
XDEBUG_SESSION_STOP	Arrête la session de débogage et supprime le cookie.

Utiliser une fonction Xdebug : xdebug_break() en mode Trigger :

L’appel à xdebug_break() déclenchera une connexion de débogage tant que xdebug.start_with_request est défini sur trigger et qu’aucune session de débogage n’est active.
Cela revient au même que de placer un point d’arrêt dans son IDE.
Si une session de débogage est déjà active, l’appel à xdebug_break() agira comme si un point d’arrêt avait été défini via l’IDE.

Déboguer en utilisant PHP en ligne de commande :

Si vous exécutez vos scripts PHP en ligne de commande, vous pouvez définir la variable d’environnement XDEBUG_TRIGGER.

Xdebug avec le mode Off

Rien n’est activé. Xdebug ne fait rien d’autre que vérifier si une fonctionnalité est activée.
Utilisez ce paramètre si vous souhaitez une surcharge proche de zéro.

Débogueur avec Xdebug et Docker :

Il est possible de faire fonctionner Xdebug et Docker ensemble : Xdebug sera installé dans le conteneur.

Installer Xdebug dans votre conteneur PHP :
Il faut modifier le fichier Dockerfile pour installer l’extension Xdebug directement dans le conteneur Docker.

Exemple de script pour l’installation de Xdebug en fonction de la version de PHP installée dans le conteneur (il est également possible de spécifier une version précise).

Exposer l’IP du conteneur Docker à la machine hôte :
host.docker.internal est un nom DNS spécial qui pointe vers l’IP de la machine hôte, depuis l’intérieur d’un conteneur Docker.
Il est utilisé pour permettre au conteneur de communiquer avec l’hôte (par exemple, lorsque Xdebug, dans le conteneur, doit se connecter à ton IDE sur ta machine).

Dans le cas où cela ne serait pas supporté, tu peux utiliser directement l’IP de la machine hôte.

Configurer l’IDE pour placer des points d’arrêt (ex : VSCode) :
Le chemin /var/www/html/ représente le répertoire où votre code PHP est monté dans le conteneur Docker.

Pour adapter ce chemin en fonction des projets, il faut entrer dans le conteneur et vérifier où se trouvent les fichiers de l’application web.
${workspaceFolder} est une variable de Visual Studio Code qui représente le dossier de votre espace de travail local.
Grâce à cela, Visual Studio Code sait où se trouve le code source sur votre machine locale.

Déboguer sur un serveur distant :

Déboguer un serveur distant avec Xdebug permet d’analyser et d’exécuter pas à pas un script PHP hébergé à distance, tout en utilisant un IDE local comme VS Code ou PHPStorm.
Cette méthode est essentielle pour diagnostiquer des problèmes dans des environnements ne pouvant pas exécuter d’IDE, comme les serveurs de pré-production ou de production.

Installez Xdebug sur le serveur distant, puis ajoutez ou modifiez les paramètres suivants.
Assurez-vous que le port utilisé par Xdebug (par défaut 9003 avec Xdebug 3) est ouvert sur votre pare-feu et, si besoin, redirigé sur votre routeur pour permettre la connexion entrante depuis le serveur distant.

Dans VS Code ou PHPStorm, activez l’écoute du port Xdebug (ex. : “Listen for Xdebug”).
Configurez le mapping des chemins (path mapping) entre les fichiers du serveur distant et votre projet local, afin que l’IDE reconnaisse les fichiers exécutés à distance.

Déboguer sur un serveur distant en utilisant un tunnel SSH :

Dans le fichier de configuration du serveur, configurez Xdebug pour pointer vers 127.0.0.1 (qui, via le tunnel SSH, pointera vers votre machine locale).

Créer le tunnel SSH : sur votre machine locale, ouvrez un terminal et exécutez la commande SSH.
Une fois le tunnel créé, vous pouvez placer des breakpoints dans votre IDE et exécuter des requêtes sur le serveur distant.

Le tunnel SSH doit rester actif pendant toute la session de débogage.
Le serveur distant exécute le code PHP, et Xdebug tente de se connecter à 127.0.0.1:9003 (côté serveur).
Grâce au tunnel SSH, cette connexion est redirigée vers votre machine locale sur le port 9003.
VS Code, en mode écoute, reçoit la connexion et vous permet de déboguer comme en local.

Dans le fichier /etc/ssh/sshd_config du serveur distant, assurez-vous que la redirection de port est autorisée :

Identifier une session de débogage avec xdebug.idekey (serveur partagé) :

Le paramètre xdebug.idekey est une option de configuration dans Xdebug qui permet d’identifier une session de débogage spécifique et de la relier à un IDE (comme PhpStorm, Visual Studio Code, NetBeans, etc.).
Il joue un rôle important dans la communication entre Xdebug et l’IDE. Il est essentiel pour gérer plusieurs développeurs ou IDE sur un même serveur.

Si plusieurs sessions de débogage sont déclenchées simultanément (par exemple, sur un serveur partagé), Xdebug utilise la valeur de xdebug.idekey pour s’assurer que chaque session est envoyée au bon IDE.

Configuration Réseau :

Le paramètre xdebug.client_host est utilisé par Xdebug pour se connecter à un débogueur local ou distant.
Il définit l’adresse IP ou le nom d’hôte du serveur où l’IDE (comme PhpStorm, VS Code, NetBeans) attend les connexions de débogage.

Le paramètre xdebug.client_port définit le port de connexion à l’IDE. Celui-ci est défini à 9003 par défaut.
Si ce port est utilisé par un autre service ou bloqué, vous pouvez en choisir un autre, comme 9010.
Attention : il faut également configurer l’IDE pour écouter sur ce même port.

Astuce : si vous utilisez plusieurs instances de VS Code en parallèle, vous ne pourrez pas utiliser Xdebug sur toutes en même temps avec le même port.
Dans ce cas, modifiez le port et attribuez un port différent à chaque projet (ex : 9004, 9005, 9006, etc.).

Fonction incluse avec XDebug

XDebug arrivent avec plein de fonction prete à l’emploie, qui peut etre utilisé dans les
diffèrent scripts PHP, on peut retrouver la documentation de l’ensensemble des fonctions ici
https://xdebug.org/docs/all_functions ( xdebug_info() et xdebug_break() en font partie

Voir la configuration complète d’Xdebug avec xdebug_info() :

Xdebug arrive avec de nombreuses fonctions prêtes à l’emploi, qui peuvent être utilisées dans différents scripts PHP.
Vous pouvez retrouver la documentation complète de ces fonctions ici : https://xdebug.org/docs/all_functions
(xdebug_info() et xdebug_break() en font partie).

Connaître votre version de Xdebug et les différents paramètres de configuration de Xdebug

Pour cela, vous pouvez consulter directement votre phpinfo(), qui vous donnera l’ensemble de la configuration de votre PHP, ainsi que celle de vos extensions, y compris Xdebug.

Passage à la version 3 de Xdebug :

Xdebug 3 est la dernière version majeure de l’extension Xdebug pour le débogage et le profilage.
Cependant, plusieurs changements ont été opérés lors de la mise à jour de Xdebug.

Séparation des fonctionnalités :
Dans Xdebug 2, toutes les fonctionnalités étaient regroupées dans une seule extension.
En revanche, Xdebug 3 a introduit une séparation des fonctionnalités en plusieurs composants distincts : un pour le débogage, un pour le profilage, un pour la couverture du code, etc.
Cela permet d’activer ou de désactiver les fonctionnalités individuellement, en fonction des besoins spécifiques.

La configuration des options de Xdebug 3 a été revue et simplifiée. Certaines directives de configuration ont été supprimées ou renommées afin de rendre la configuration plus claire et plus intuitive.
https://xdebug.org/docs/upgrade_guide

Cependant, pour utiliser la version 3 de Xdebug, vous devez disposer d’une version minimale de PHP.
Si vous utilisez une version trop ancienne, cela ne fonctionnera pas.
Version minimale requise pour Xdebug 3 : PHP 7.2.

Débogage : activer les logs de Xdebug :

Xdebug permet d’écrire des logs détaillés sur ses connexions. Pour les activer, ajoutez ces lignes dans votre php.ini ou xdebug.ini.

touch /var/log/xdebug.log && chmod 666 /var/log/xdebug.log

Une fois activé, Xdebug va enregistrer des informations telles que : les requêtes reçues, les tentatives de connexion à l’IDE (hôte, port, etc.), et les éventuelles erreurs (échec de connexion, IDE injoignable, etc.).
Les messages de type Critical et Error sont également enregistrés via le mécanisme de journalisation interne de PHP (configuré avec error_log dans le php.ini).

Conflit entre XDebug et l’OPCache :

OPcache (Optimized Opcode Cache) est une extension PHP conçue pour améliorer les performances des applications PHP.
Elle fonctionne en mettant en cache les opcodes (ou “code opérationnel”) des scripts PHP, ce qui permet d’éviter la recompilation des scripts à chaque exécution.

Un opcode (abréviation de “operation code”) est une représentation intermédiaire du code source PHP, générée après la phase de compilation.
Il s’agit d’un ensemble d’instructions bas niveau que le moteur Zend de PHP peut exécuter directement.

Ordre de chargement des extensions PHP :

Pour éviter les conflits et garantir un fonctionnement optimal, OPcache doit être chargé avant Xdebug.
Cela signifie que la directive zend_extension pour OPcache doit apparaître avant celle de Xdebug dans le fichier php.ini ou dans les fichiers de configuration.

Dans le dossier conf.d/, les fichiers sont chargés dans l’ordre alphabétique.
Par exemple : 10-opcache.ini sera chargé avant 20-xdebug.ini.

Voir l’ordre de chargement des fichiers de configuration avec la commande php --ini, ou dans le fichier phpinfo() à la rubrique Additional .ini files parsed.

Lorsque OPcache est activé, il met en cache les scripts PHP compilés. Si vous modifiez un fichier PHP, OPcache peut continuer à exécuter l’ancienne version mise en cache, ce qui peut poser problème lors du débogage avec Xdebug.

Si OPcache ne détecte pas les modifications du code (par exemple, si opcache.revalidate_freq est mal configuré), Xdebug pourrait déboguer une version obsolète du code.
Il s’agit de la fréquence (en secondes) à laquelle OPcache vérifie si un fichier PHP a été modifié.

Lorsque opcache.validate_timestamps est désactivé, les fichiers PHP ne sont pas périodiquement purgés par OPcache.
Dans ce cas, vous devrez réinitialiser manuellement le cache PHP.

Lorsqu’elle est activée, l’option opcache.validate_timestamps demande à OPcache de vérifier automatiquement les modifications des fichiers PHP, toutes les 15 secondes par défaut, ou toutes les opcache.revalidate_freq secondes, si ce paramètre a été modifié.

Fonctionnalités additionnelles de Xdebug (trace, profile, gcstat) :

En plus de ses fonctionnalités classiques comme le débogage à distance ou le stack trace amélioré, Xdebug propose plusieurs fonctionnalités additionnelles très utiles : trace, profile et gcstats. Passons-les en revue rapidement.

Trace – Capturer toutes les fonctions appelées avec Xdebug :

But : suivre l’exécution de chaque fonction appelée dans ton script PHP, dans l’ordre, avec :

• Le nom de la fonction
• Les arguments passés
• Le temps d’exécution de chaque fonction
• La mémoire utilisée

Utile pour :

• Comprendre le comportement de ton code
• Détecter les fonctions lentes ou inutiles
• Déboguer plus finement qu’avec un simple var_dump() ou echo

Profile – Effectuer du profilage avec Xdebug :

But : mesurer les performances globales de ton application PHP.

Génère un fichier de profil au format Cachegrind (compatible avec des outils comme KCachegrind ou Webgrind).
Enregistre :

• Le temps CPU et la mémoire utilisée pour chaque fonction
• Le nombre d’appels de chaque fonction
• Le graphe d’appel entre les fonctions (call graph)

Utile pour :

• Optimiser le code
• Identifier les goulots d’étranglement
• Suivre l’impact des changements sur les performances

En plus de Xdebug, il existe plusieurs autres outils de profilage pour PHP, chacun avec ses avantages selon le contexte.
On peut citer par exemple Blackfire ou encore XHProf.

GCStats – Statistiques du Garbage Collector :

Objectif : voir combien de cycles GC sont exécutés, combien d’objets sont nettoyés, etc.
But : diagnostiquer les performances liées au ramasse-miettes (garbage collector) de PHP
Ce que ça fait :

• Enregistre quand le GC est déclenché
• Combien de cycles il effectue
• Combien d’objets sont nettoyés
• Le temps passé dans le GC

Utile pour :

• Comprendre les problèmes de fuites de mémoire
• Optimiser les structures d’objets ou les boucles
• Vérifier si le GC s’active trop souvent (ce qui peut ralentir ton application)

Bonus : la chaîne YouTube du créateur de Xdebug :

Le créateur de l’extension Xdebug possède une chaîne YouTube, où il publie des vidéos de configuration et d’utilisation plus ou moins avancées de Xdebug :
https://www.youtube.com/@DerickRethansXdebug/videos