Débugger efficacement un projet Php Symfony

Si debugger, c’est supprimer des bugs, alors programmer ne peut être que les ajouter — Edsger Dijkstra. Vous l’avez compris, quel que soit votre niveau, vos années d’expérience, le language de programmation que vous allez utiliser, une partie de votre quotidien consistera à débugger du code source.

Une anomalie peut être compliquée à trouver, comme parfois l’aguille dans une botte de foin : elle peut déprendre de nombreux paramètres, d’un contexte d’exécution particulier, de la présence (ou non) de certaines données, d’effets de bords, de «edges cases», et pourtant…

Pourtant il n’est pas rare (pas vous hein, votre voisin) de faire un echo "coucou;" die(); pour essayer d’y voir plus clair dans tout ce sac de noeuds…

Bien entendu, il existe des outils, tels que Xdebug, qui permettent bien mieux qu’un dump() de tracer le comportement de votre projet PHP pour identifier et résoudre les anomalies.

Dans cet article, nous allons voir comment mettre en place un debug comme dans la vraie vie, avec #php, #symfony, (#symfony-cli | #docker), (#phpstom | #VSCode)

Première étape : installer Xdebug

---

Avec Docker

Pour disposer de Xdebug dans votre conteneur, il vous suffira d’ajouter ces lignes à votre Dockerfile

FROM php:7.4-fpm # Version de PHP que vous voulez
RUN pecl install -f xdebug \
        && echo "zend_extension=$(find /usr/local/lib/php/extensions/ -name xdebug.so)\nxdebug.mode=debug\nxdebug.start_with_request=yes" > /usr/local/etc/php/conf.d/xdebug.ini;

Pensez également à ajouter ces deux variables d’environnement à votre conteneur:

environment:
  - XDEBUG_CONFIG=client_host=host.docker.internal client_port=9000
  - PHP_IDE_CONFIG=serverName=acseo-docker

Sans Docker

Pour disposer de Xdebug avec PHP, il vous suffira de l’installer vie pecl

# Avec Symfony CLI
$ symfony pecl install -f xdebug
# Sans Symfony CLI
$ pecl install -f xdebug

Deuxième étape : utiliser XDebug sur votre projet

---

Avec Visual Studio Code

En cas de besoins spécifiques, il est possible d’éditer le fichier .vscode/launch.json pour paramétrer comme vous le souhaitez le fonctionnement du debug

{
    "version": "0.2.0",
    "configurations": [
    {
        "name": "Listen for XDebug",
        "type": "php",
        "request": "launch",
        "port": 9000,
        "pathMappings": {
            "/app": "${workspaceFolder}"
        },
        "xdebugSettings": {
            "max_data": 65535,
            "show_hidden": 1,
            "max_children": 100,
            "max_depth": 5
        }
    }
    ]
}

Avec PHPStorm

Vous utilisez PHPStorm, il est encore temps de changer pour un autre IDE. Si malgré tout vous persistez, voici les étapes à suivre pour Débugger votre projet.

Configurer un Server

Une fois votre projet lancé, rendez vous dans PHPStorm > Preferences > Languages & Frameworks > PHP > Servers

Puis configurez un serveur avec les caractéristiques suivantes :

• Name : acseo-docker (important)
• Host : localhost
• Port : 80 (renseigné par défaut)
• Debugger : XDebug (renseigné par défaut)
• Cocher la case Use path mappings
• Sur la ligne File / Directory correspondant à votre projet, renseigner la valeur /app dans la colonne absolute path on the server

Ajouter une configuration

Rendez vous dans Run > Edit configurations.

Cliquez sur le + Add a new configuration et choisissez PHP Remote Debug

Renseignez les paramètres suivants :

• Name : symfony-stack-debug
• Cocher la case Filter debug connection by IDE key
• Server : sélectionner acseo-docker
• IDE key : vous pouvez laisser vide, cette valeur n’est pas utilisée

Enregistrez en cliquant sur OK

Et voilà ! Il ne vous reste plus qu’à lancer le debug (Menu Run > symfony-stack-debug), à placer un point d’arrêt et à lancer votre navigateur.

Conclusion

Il est assez simple et rapide de mettre en place XDebug avec un environnement Docker et des IDE très répandus comme PHPStorm et Symfony.

L’utilisation de XDebug dans votre stack PHP7 FPM / XDebug / Symfony / Docker vous permettra de gagner un temps précieux pour comprendre l’origine de vos bugs à travers une exécution pas à pas de votre code.

L’essayer, c’est l’adopter 😉

Mise à jour du 19/11/2024

Suite à un message reçu de la part d’un Lecteur (que nous remercions), voici quelques informations si vous rencontrez des problèmes de performances avec XDebug :

Je suis tombé sur votre article https://www.acseo.fr/developpement/debugger-efficacement-php-symfony/
en cherchant la raison pour laquelle le chargement d’une page toute simple est extrêmement lente (plus de 15s) lorsque la toolbar Symfony est active et que xdebug est activé en mode pas-à-pas (xdebug.mode=debug).

Cela se produit à partir du moment où xdebug est activé au niveau du navigateur, que l’écoute soit activée ou non au niveau de l’IDE.

Il s’avère que la toolbar Symfony est chargée à l’aide d’une requête XHR qui contient le paramètre XDEBUG_IGNORE=1 afin d’éviter que xdebug ralentisse son chargement, mais cela n’est pris en compte qu’à partir de la version 3.4.0alpha1 de Xdebug qui est sortie le 31 mai 2024 (https://xdebug.org/updates).

A l’heure où j’écris ces lignes, il n’existe pas de version stable de Xdebug qui contient ce patch, puisque la dernière version disponible est la 3.4.0beta1 sortie le 4 octobre 2024.

Avec xdebug >= 3.4.0alpha1, on passe de >=15s à environ 200ms pour charger une page basique avec la toolbar Symfony active, ce qui est quand même beaucoup plus confortable et efficace pour développer.

Je vous invite donc à mettre à jour votre article pour donner cette information à vos lecteurs.

Cordialement,
Olivier Blanc

Liens complémentaires :
– l’issue Xdebug corrigée : https://bugs.xdebug.org/bug_view_page.php?bug_id=00002239

– la pull Request Symfony : https://github.com/symfony/symfony/pull/52950