Comment activer et configurer Xdebug dans ServBay

ServBay, en tant qu’environnement local de développement Web puissant, intègre d’office l’outil de débogage et d’analyse Xdebug pour les développeurs PHP. L’activation de Xdebug augmente significativement l’efficacité du développement PHP en rendant le débogage du code, l’analyse des performances et la couverture de code beaucoup plus aisés. Ce guide vous explique en détail comment activer et configurer Xdebug dans ServBay, et vous accompagne pour son intégration dans des environnements de développement intégrés (IDE) populaires.

Présentation du module Xdebug

Xdebug est une extension PHP puissante conçue pour le débogage et l’analyse de code PHP. Grâce à son intégration native dans ServBay, vous n’avez plus à vous soucier de l’installation ou de la compilation manuelle : activer et configurer Xdebug devient un jeu d’enfant.

Fonctions principales de Xdebug

Débogage par points d’arrêt : Permet de placer des points d’arrêt sur des lignes spécifiques du code. L’exécution du code s’arrête au point d’arrêt, ce qui vous permet d’inspecter les variables et la pile d’appels ligne par ligne.
Débogage pas à pas : Prend en charge l’exécution étape par étape (Step Over), l’entrée dans une fonction (Step Into), ou la sortie d’une fonction (Step Out), facilitant ainsi la compréhension du parcours d’exécution du programme.
Surveillance des variables : Affiche en temps réel la valeur des variables locales et globales lors du débogage.
Piste de la pile d’appels : En cas d’erreur ou d’exception, fournit des informations complètes sur la pile d’appels, ce qui accélère la localisation du problème.
Analyse de performances (Profiling) : Génère des rapports de performance sur l’exécution du code pour identifier les goulots d’étranglement.
Analyse de couverture de code : Mesure la part du code effectivement couverte par les tests pour estimer leur efficacité.

Versions Xdebug intégrées à ServBay et correspondance des ports

ServBay propose un module Xdebug adapté à chaque version de PHP préinstallée. Il est important de noter que chaque version de PHP utilise un port d’écoute Xdebug indépendant, lié à sa version. Ce détail est crucial pour configurer votre débogueur dans l’IDE.

Version PHP	Version Xdebug préinstallée	Port d’écoute Xdebug par défaut
PHP 5.6	Xdebug 2.5.5	39056
PHP 7.0	Xdebug 2.5.5	39070
PHP 7.1	Xdebug 2.5.5	39071
PHP 7.2	Xdebug 3.1.6	39072
PHP 7.3	Xdebug 3.1.6	39073
PHP 7.4	Xdebug 3.1.6	39074
PHP 8.0	Xdebug 3.3.1	39080
PHP 8.1	Xdebug 3.4.0	39081
PHP 8.2	Xdebug 3.4.0	39082
PHP 8.3	Xdebug 3.4.0	39083
PHP 8.4	Xdebug 3.4.0	39084
PHP 8.5	Xdebug 3.4.0	39085

Règle des ports

La règle pour le port d’écoute Xdebug par défaut est 39000 + numéro secondaire de version PHP. Par exemple, le port pour PHP 8.3 est 39000 + 83 = 39083, tandis que pour PHP 7.4 il s’agit de 39000 + 74 = 39074. Comprendre cette règle vous aide à retrouver rapidement le port Xdebug selon la version PHP utilisée.

Comment activer le module Xdebug

Activer Xdebug dans ServBay est très simple, et il est recommandé de passer par l’interface graphique (GUI). Vous pouvez également effectuer une activation manuelle en éditant les fichiers de configuration.

Activer Xdebug via l’interface graphique de ServBay

Il s’agit de la méthode la plus simple et rapide.

Ouvrez l’application ServBay.
Dans le menu à gauche, sélectionnez Langages.
Déployez la section PHP, puis choisissez la version PHP pour laquelle vous souhaitez activer Xdebug, par exemple PHP 8.3.
Cliquez sur le bouton Extensions situé à droite de cette version.
Dans la liste des extensions qui apparaît, repérez le module Xdebug.
Activez l’interrupteur à gauche de Xdebug pour la passer de désactivée à activée.
Modifiez les paramètres si nécessaire.
Cliquez sur le bouton Sauvegarder en bas de l’interface.
ServBay redémarrera automatiquement le processus PHP pour charger le module.

Illustration : Activation de Xdebug dans Extensions

Vérifier si le module Xdebug est bien activé

La méthode la plus fiable consiste à consulter la configuration PHP avec phpinfo().

Dans le dossier racine de votre site sous ServBay (par défaut /Applications/ServBay/www), créez un fichier PHP simple, par exemple phpinfo.php.
Ajoutez le contenu suivant dans ce fichier :
php
```
<?php
phpinfo();
?>
```
1
2
3
Accédez à ce fichier via un navigateur, par exemple https://servbay.demo/phpinfo.php (remplacez servbay.demo par le domaine configuré dans ServBay pour votre site).
Dans la page phpinfo, cherchez "Xdebug". Si le module est bien activé, une section "Xdebug" s’affichera avec le numéro de version et les paramètres de configuration.

Illustration : Localiser les informations Xdebug dans la sortie phpinfo

Configurer Xdebug dans votre IDE pour le débogage

L’activation de Xdebug n’est que la première étape. Pour profiter réellement du débogage par points d’arrêt, vous devez configurer l’interpréteur PHP, le débogueur et le mapping du serveur dans votre IDE. Voici comment faire dans PHPStorm et Visual Studio Code (VS Code).

Configurer Xdebug dans PHPStorm

PHPStorm offre un support natif et avancé pour Xdebug.

Ouvrir les paramètres de PHPStorm : Lancez PHPStorm, puis ouvrez le menu File -> Settings (Windows/Linux) ou PHPStorm -> Preferences (macOS).
Configurer l’interpréteur CLI PHP :
- Accédez à Languages & Frameworks -> PHP.
- Dans la section CLI Interpreter, cliquez sur le bouton ... à droite.
- Cliquez sur le + pour ajouter un nouvel interpréteur local.
- Indiquez le chemin de l’exécutable PHP correspondant à la version souhaitée de votre installation ServBay, par exemple /Applications/ServBay/package/php/8.3/8.3.7/bin/php (le numéro de version peut varier selon les mises à jour de ServBay).
- PHPStorm détecte alors automatiquement la version du PHP et l’état de ses extensions, y compris Xdebug.
- Cliquez sur OK pour sauvegarder la configuration. Illustration : Configuration de l’interpréteur CLI PHP de ServBay dans PHPStorm
Configurer les paramètres de débogage Xdebug :
- Rendez-vous dans Languages & Frameworks -> PHP -> Debug.
- Dans la section Xdebug, fixez le Debug Port correspondant au port Xdebug utilisé par la version PHP active sous ServBay (par exemple, 39083 pour PHP 8.3). Assurez-vous qu’il correspond à la valeur de xdebug.client_port.
- Cochez Peut accepter les connexions externes.
- Cliquez sur Appliquer puis OK. Illustration : Attribution du port d’écoute Xdebug dans PHPStorm
Définir la correspondance des serveurs web :
- Allez dans Languages & Frameworks -> PHP -> Servers.
- Cliquez sur le + à droite pour ajouter un nouveau serveur.
- Donnez-lui un nom (exemple : ServBay Localhost).
- Renseignez Host avec le domaine associé dans ServBay (exemple : servbay.demo).
- Spécifiez le Port utilisé (généralement 443 pour HTTPS ou 80 pour HTTP).
- Choisissez Xdebug comme débogueur.
- Cochez l’option Utiliser le mapping de chemins.
- Définissez la correspondance entre le chemin local du projet (Absolute path to local source) et le chemin sur le serveur (Absolute path on the server). Par exemple, si votre projet se situe dans /Applications/ServBay/www/myproject et que vous y accédez via https://servbay.demo/, le chemin local /Applications/ServBay/www/myproject doit correspondre au chemin serveur /. Si vous utilisez https://myproject.servbay.demo/, la racine du projet locale /Applications/ServBay/www/myproject correspond également à /. Ce mapping est crucial pour un débogage correct avec Xdebug.
- Cliquez sur OK pour sauvegarder. Illustration : Mapping serveur et chemins dans PHPStorm
Lancer une session de débogage :
- Ouvrez un fichier PHP de votre projet dans PHPStorm.
- Placez des points d’arrêt en cliquant dans la marge à gauche des numéros de lignes.
- Cliquez sur le bouton Démarrer l’écoute des connexions de débogage PHP (icône de scarabée en haut). L’icône devient verte, indiquant que PHPStorm écoute les connexions Xdebug.
- Accédez à votre application PHP dans le navigateur (ex : https://servbay.demo/index.php).
- Si tout est bien configuré, Xdebug connectera automatiquement PHPStorm et l’exécution du code s’arrêtera sur vos points d’arrêt. Illustration : Activer l’écoute Xdebug dans PHPStorm

Configurer Xdebug dans Visual Studio Code (VS Code)

VS Code, éditeur populaire, offre un support efficace de Xdebug grâce à des extensions dédiées.

Installer l’extension PHP Debug :
- Ouvrez VS Code.
- Passez à la vue extensions (Ctrl+Shift+X ou Cmd+Shift+X).
- Cherchez "PHP Debug" et installez l’extension de Felix Becker.

Configurer launch.json :

Ouvrez le dossier de votre projet PHP sous VS Code.
Passez à la vue Exécution et débogage (Ctrl+Shift+D ou Cmd+Shift+D).
Cliquez sur l’icône d’engrenage en haut et choisissez "PHP". Un fichier launch.json sera créé dans le dossier .vscode du projet.
Modifiez ce fichier pour vous assurer que le paramètre port correspond au port Xdebug utilisé avec votre version PHP dans ServBay (par exemple 39083 pour PHP 8.3).

Configurer le mapping de chemins (pathMappings) : C’est essentiel pour que Xdebug retrouve vos fichiers locaux. Dans launch.json, repérez ou ajoutez l’option pathMappings pour relier le dossier serveur à votre système de fichiers local.

json

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 39083, // Modifiez ce port selon votre version PHP
            "pathMappings": {
                // Faites correspondre le chemin projet sur le serveur au dossier local
                // Par exemple, pour un projet dans /Applications/ServBay/www/myproject
                // accessible via https://servbay.demo/, la racine serveur '/' correspond à celle du projet local
                "/": "${workspaceRoot}"
                // Même correspondance pour https://myproject.servbay.demo/
            }
        },
        {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 39083 // Adaptez ce port selon la version PHP
        }
    ]
}

Adaptez pathMappings selon la structure de votre projet et la configuration du site dans ServBay. ${workspaceRoot} indique en général la racine du dossier projet ouvert dans VS Code.

Démarrer une session de débogage :
- Ouvrez un fichier PHP dans VS Code.
- Placez des points d’arrêt en cliquant à gauche des numéros de lignes.
- Passez en mode Exécution et débogage (Ctrl+Shift+D ou Cmd+Shift+D).
- Sélectionnez la configuration "Listen for Xdebug".
- Cliquez sur le bouton vert pour démarrer le débogage. La barre d’état de VS Code devient orange, indiquant qu’elle écoute Xdebug.
- Lancez votre application PHP dans le navigateur. Si tout est correctement configuré, Xdebug se connectera à VS Code et s’arrêtera sur les points d’arrêt.

FAQ - Questions fréquentes

Q : Le module Xdebug n’apparaît pas dans phpinfo() ?
- R : Vérifiez que vous avez activé Xdebug via l’interface graphique ServBay ou en éditant manuellement xdebug.ini.
- Assurez-vous d’avoir redémarré le service PHP concerné.
- Contrôlez le chemin du fichier xdebug.ini et que la ligne zend_extension = xdebug.so n’est pas commentée.
- Consultez les logs ServBay (/Applications/ServBay/logs/php/<version>/error.log) pour d’éventuels messages d’erreur sur le chargement de Xdebug.
Q : Les points d’arrêt dans l’IDE ne sont pas atteints ?
- R : Vérifiez que votre IDE écoute bien les connexions Xdebug (icône scarabée verte dans PHPStorm, barre orange dans VS Code).
- Assurez-vous que le port d’écoute Xdebug dans l’IDE correspond à la configuration ServBay xdebug.client_port pour votre version PHP.
- Vérifiez que le mapping de chemins entre le serveur et votre projet local est juste – c’est la cause la plus fréquente de dysfonctionnement Xdebug.
- Contrôlez le pare-feu pour vous assurer qu’il ne bloque pas le port d’écoute de Xdebug (390xx).
- Si xdebug.start_with_request=trigger est activé dans xdebug.ini, vérifiez que vous utilisez un déclencheur (par exemple, avec une extension navigateur Xdebug Helper ou en ajoutant ?XDEBUG_TRIGGER=1 à l’URL).
Q : La connexion Xdebug s’interrompt après un moment ?
- R : Inspectez les paramètres xdebug.remote_autostart ou xdebug.start_with_request dans xdebug.ini. Une activation sur yes déclenchera le débogage à chaque requête : préférez le mode trigger.
- Regardez les paramètres de délai d’attente du débogueur dans votre IDE.

Conclusion

Grâce à son intégration native et des outils de configuration simplifiés, ServBay abaisse considérablement la barrière d’entrée pour les développeurs PHP souhaitant utiliser Xdebug. Que vous passiez par une interface graphique conviviale ou en éditant manuellement les fichiers de configuration, vous pouvez activer Xdebug rapidement pour différentes versions de PHP dans ServBay. Associé aux fonctionnalités avancées de débogage de PHPStorm, VS Code et d’autres IDE majeurs, vous bénéficierez d’un environnement propice à l’optimisation, à la qualité et à la productivité dans vos développements PHP. Maîtriser l’articulation entre ServBay et Xdebug deviendra un atout indispensable à votre workflow de développement local PHP.

Comment activer et configurer Xdebug dans ServBay ​

Présentation du module Xdebug ​

Fonctions principales de Xdebug ​

Versions Xdebug intégrées à ServBay et correspondance des ports ​

Comment activer le module Xdebug ​

Activer Xdebug via l’interface graphique de ServBay ​

Vérifier si le module Xdebug est bien activé ​

Configurer Xdebug dans votre IDE pour le débogage ​

Configurer Xdebug dans PHPStorm ​

Configurer Xdebug dans Visual Studio Code (VS Code) ​

FAQ - Questions fréquentes ​

Conclusion ​