Xdebug pour déboguer du code PHP à distance

Xdebug permet de parcourir du code PHP avec des points d'arrêt et d'examiner les variables d'une requête depuis un IDE compatible.

Utilisez-le de préférence en local ou en staging. Une session pas à pas peut exposer à l'IDE des valeurs de variables, des identifiants, des jetons et des données personnelles traités par la requête. Si vous devez exceptionnellement l'utiliser en production, limitez le test à une requête autorisée, utilisez un déclencheur privé et désactivez l'extension immédiatement une fois terminé.

Xdebug peut introduire une surcharge notable selon le mode activé et désactive le JIT de PHP tant qu'il est chargé. Vérifiez sa version réelle ; ne la déduisez pas uniquement de la version de PHP.

Vérifier la disponibilité et activer Xdebug 3

Allez dans cPanel > Sélectionner une version de PHP pour la version qui exécute le chemin concerné. Ce guide ne s'applique que si le sélecteur propose l'extension xdebug et, dans Options, l'option xdebug.mode. Activez l'extension et définissez xdebug.mode sur debug. Cette option s'applique au démarrage de PHP et ne peut pas être définie depuis .htaccess ni .user.ini.

Si l'une de ces options n'apparaît pas, ne supposez pas que Xdebug est disponible pour cette version. N'essayez pas d'installer ni de charger une autre extension dans le compte.

Si le gestionnaire PHP du domaine accepte les directives Xdebug dans .htaccess, ajoutez temporairement :

php_value xdebug.start_with_request trigger
php_flag xdebug.start_upon_error Off
php_flag xdebug.discover_client_host Off
php_value xdebug.client_host 127.0.0.1
php_value xdebug.client_port 9003
php_value xdebug.trigger_value VALOR_ALEATORIO_LARGO

Remplacez VALOR_ALEATORIO_LARGO par une valeur privée. Ces options imposent le démarrage par déclencheur, désactivent le démarrage automatique sur erreur et évitent de découvrir la destination à partir des en-têtes. Vérifiez leurs valeurs effectives : un code qui appelle xdebug_break() peut aussi lancer une connexion. Le déclencheur privé contrôle le test habituel, mais ce n'est pas un mécanisme d'authentification du protocole. Si les directives provoquent une erreur 500, retirez-les et consultez le journal : le code seul ne prouve pas que le gestionnaire les refuse.

Créer un tunnel SSH inverse

C'est Xdebug qui ouvre la connexion vers l'IDE ; l'IDE ne se connecte pas à Xdebug. Dans cette configuration, Xdebug se connecte à 127.0.0.1:9003 sur le serveur et le tunnel SSH redirige cette connexion vers 127.0.0.1:9003 sur votre ordinateur, où l'IDE est à l'écoute.

Activez au préalable l'accès SSH et configurez une clé en suivant le guide d'accès SSH.

Sous Linux ou macOS, exécutez :

ssh -N -p 93 \
  -o ExitOnForwardFailure=yes \
  -R 127.0.0.1:9003:127.0.0.1:9003 \
  USUARIO_CPANEL@TU_DOMINIO.COM

-R ouvre le port 9003 uniquement sur l'interface de loopback du serveur et le redirige vers le port 9003 de votre ordinateur. Gardez la session ouverte uniquement pendant le test. Si SSH ne peut pas créer la redirection, il s'arrêtera avec une erreur ; n'exposez pas à la place le port du débogueur sur Internet.

Sous Windows, configurez PuTTY avec le domaine et le port 93, en utilisant la clé SSH autorisée dans cPanel. Dans Connection | SSH | Tunnels, créez une redirection Remote depuis 127.0.0.1:9003 vers la destination 127.0.0.1:9003. N'activez pas d'options permettant d'écouter sur d'autres interfaces du serveur. Si la session refuse la redirection distante, cette méthode n'est pas disponible pour le compte.

Configurer l'IDE et reproduire la requête

Ouvrez dans l'IDE la même version du code que celle déployée et configurez la correspondance entre le chemin distant et le projet local. Configurez le port Xdebug 9003, activez l'écoute des connexions et ajoutez les points d'arrêt.

Dans PhpStorm, utilisez Run > Start Listening for PHP Debug Connections. Dans NetBeans, configurez le port 9003 et la correspondance des chemins distants. Il n'est pas nécessaire de synchroniser le projet par FTP pour recevoir une session de débogage.

Activez le déclencheur avec une extension de navigateur compatible configurée avec la même valeur privée, ou ajoutez XDEBUG_TRIGGER=VALOR_ALEATORIO_LARGO uniquement à la requête de test. Reproduisez l'opération nécessaire une seule fois. Accéder à l'URL sans le déclencheur ne doit pas lancer la session.

Une fois terminé, désactivez le déclencheur, fermez le tunnel SSH, supprimez les directives temporaires, passez xdebug.mode à off ou désactivez l'extension, et vérifiez qu'il ne reste aucun journal de Xdebug contenant des données de la session.

Si vous devez analyser les performances plutôt que parcourir le code, utilisez PHP X-Ray.

Limites du tunnel et vérification

Le loopback évite d'écouter sur une interface publique, mais ne garantit pas l'isolement entre tous les utilisateurs d'un serveur mutualisé. Confirmez auprès du fournisseur que la redirection est autorisée et isolée pour votre environnement. Si le port est occupé, convenez d'un autre port distant et ajustez xdebug.client_port ; ne modifiez pas les données d'un autre utilisateur.

Vérifiez d'abord qu'une requête sans déclencheur ne lance pas la session, puis que la requête de test atteint le bon point d'arrêt. Ne publiez pas d'URL contenant le déclencheur : elle peut rester dans des historiques ou des journaux. Supprimez aussi le cookie de débogage une fois terminé. Consultez les options de débogage de Xdebug si la session démarre de manière inattendue.