Installation de l'extension Xdebug dans VS Code

Pour intégrer les fonctionnalités de débogage, accédez à la marketplace de Visual Studio Code, recherchez l'extension PHP Debug et procédez à son installation.

Activation du module Xdebug dans PhpStudy

Dans l'interface de gestion de PhpStudy, sélectionnez la version de PHP cible pour votre projet (par exemple, la version 7.4.3). Ouvrez le panneau de configuration des extensions et activez le composant Xdebug. Le port d'écoute par défaut peut être modifié selon vos besoins réseau.

Configuration du fichier php.ini

Toujours dans PhpStudy, ouvrez le fichier php.ini associé à votre version de PHP via l'éditeur de texte intégré. Localisez la section dédiée à Xdebug à la fin du fichier et ajoutez les directives suivantes pour forcer l'activation et le démarrage automatique :

; Paramètres de débogage Xdebug
xdebug.remote_enable = On
xdebug.remote_autostart = On
xdebug.remote_handler = dbgp
xdebug.remote_port = 9000

Une fois les modifications enregistrées, redémarrez le service Apache depuis le panneau de contrôle de PhpStudy pour appliquer la nouvelle configuration.

Ajustement des paramètres de VS Code

Ouvrez les paramètres de Visual Studio Code et recherchez les options liées à PHP. Vous devez spécifier les chemins d'accès aux exécutables pour la validation syntaxique et le débogage. Modifiez le fichier settings.json en ajoutant les entrées suivantes :

{
    "php.validate.executablePath": "C:/phpstudy_pro/Extensions/php/php7.4.3nts/php.exe",
    "php.debug.executablePath": "C:/phpstudy_pro/Extensions/php/php7.4.3nts/php.exe"
}

Note : Assurez-vous d'adapter les chemins d'accès à votre installation locale et de ne pas ajouter de virgule si ces lignes sont les dernières du fichier JSON.

Génération du fichier launch.json

Dans votre espace de travail VS Code, accédez à l'onglet "Exécuter et déboguer" et cliquez sur Créer un fichier launch.json. Sélectionnez PHP dans la liste déroulante. Cela générera un fichier de configuration dans le répertoire .vscode de votre projet.

Vérifiez que les ports définis dans ce fichier correspondent à ceux configurés dans php.ini. Voici une configuration optimisée :

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Écouter les connexions Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9000
        },
        {
            "name": "Exécuter le script PHP actif",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 0,
            "runtimeArgs": [
                "-dxdebug.start_with_request=yes"
            ],
            "env": {
                "XDEBUG_MODE": "debug,develop",
                "XDEBUG_CONFIG": "client_port=${port}"
            }
        },
        {
            "name": "Démarrer le serveur web intégré",
            "type": "php",
            "request": "launch",
            "runtimeArgs": [
                "-dxdebug.mode=debug",
                "-dxdebug.start_with_request=yes",
                "-S",
                "localhost:8080"
            ],
            "program": "",
            "cwd": "${workspaceRoot}",
            "port": 9000,
            "serverReadyAction": {
                "pattern": "Development Server \\(http://localhost:([0-9]+)\\) started",
                "uriFormat": "http://localhost:%s",
                "action": "openExternally"
            }
        }
    ]
}

Débogage d'un script PHP en ligne de commende

Le débogage en ligne de commande (CLI) ne nécessite pas l'intervention du serveur web de PhpStudy. Le mécanisme repose sur l'écoute du port 9000 par VS Code. Lors de l'exécution du script, Xdebug initie une connexion vers ce port pour transmettre l'état d'exécution à l'IDE.

Pour déboguer un fichier unique, assurez-vous que la variable d'environnement PHP est correctement configurée sur votre système. Lancez d'abord la configuration Écouter les connexions Xdebug, puis exécutez Exécuter le script PHP actif. Le flux d'exécution s'interrompra aux points d'arrêt définis dans le fichier actuellement ouvert.

Débogage d'une application Web

Pour le débogage via un navigateur, Xdebug est géré par le serveur web de PhpStudy. Créez un nouvel hôte virtuel dans PhpStudy en vous assurant qu'il utilise la même version de PHP que celle configurée précédemment. Placez vos fichiers sources (par exemple, index.php) dans le répertoire racine de ce serveur.

Dans VS Code, démarrez uniquement la configuration Écouter les connexions Xdebug. Ensuite, accédez à votre application via le navigateur (ex: http://localhost/index.php). L'exécution se mettra en pause dès qu'un point d'arrêt sera atteint.

Résolution des problèmes de timeout lors du débogage Web

Lors du débogage d'applications web complexes, il est fréquent que la session de débogage se termine abruptement après environ 40 secondes. Ce comportement n'est généralement pas lié aux paramètres de timeout de PHP ou d'Xdebug, mais plutôt à la configuration du module FastCGI d'Apache.

Par défaut, le processus php-cgi est terminé par Apache s'il ne reçoit aucune réponse dans un délai restreint. Pour résoudre ce problème, modifiez le fichier de configuration d'Apache (httpd.conf ou le fichier de configuration du module FastCGI) et ajustez les directives de timeout :

<IfModule mod_fcgid.c>
    FcgidConnectTimeout 300
    FcgidIOTimeout 300
    FcgidIdleTimeout 300
    FcgidBusyTimeout 300
</IfModule>

Après avoir sauvegardé ces modifications et redémarré Apache, les sessions de débogage prolongées ne seront plus interrompues prématurément par le gestionnaire de processus CGI.