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

Installation des extensions

Installez l’extension PHP Debug. Et voilà !

Il ne vous reste plus qu’à vous placer sur la vue Debug à gauche de l’IDE, puis de vous rendre dans le menu Run > Start Debugging.

Pensez à désactiver les breakpoints inutiles dans le menu en bas à gauche de l’écran.

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 😉

Publié le 17/01/2024 à 20:58