Configurer Xdebug sur PHPStorm dans une application PHP-Docker

Introduction

Avant de rentrer dans le vif du sujet, concentrons-nous sur quelques éléments qui nous permettront d’avoir toutes les clés en main pour configurer notre débugger.

Première chose, qu’est-ce qu’un debugger, et à quoi ça peut bien servir ? Si vous n’en avez jamais entendu parler, vous allez en comprendre la puissance dans quelques lignes 😁.

Lors du développement d’application web, on ne va pas se mentir, ça ne fonctionne jamais du premier coup. On écrit des fonctions assez longues, voire complexes, et on a besoin de vérifier et tester ce que l’on fait. La manière la plus simple de le faire est bien évidemment d’afficher ce que l’on veut voir, directement depuis le navigateur :

function doesPlusWork(): void
{
    $counter = 1;
    echo $counter;
    $counter++;
    echo $counter;
    $counter++;
    echo $counter;
}

doesPlusWork();

?>

Et logiquement, votre navigateur vous affichera :

123

Bon c’est super, mais comment faire si on est confronté à un code un poil plus complexe, où plusieurs variables sont manipulées, et que l’on veut à un instant t, savoir les états de chacune d’entre elles ? Évidemment, vous pourriez me dire : « Bah je vais afficher tout ce dont j’ai besoin, et puis voilà, non ? » Oui on pourrait, mais ce n’est pas comme ça que l’on va faire.

Les limites du « echo sauvage »

Imaginons un UseCase assez simple, qui consisterait en une simple route qui nous retournerait une liste de dossiers, triés en 3 catégories public, private et other. Côté code, on organiserait donc cela en 2 classes. Premièrement, un Controller pour définir le point d’entrée :

/*
...
*/

/**
 * @var FolderUseCase
 */
private $folderUseCase;

public function __construct(FolderUseCase $folderUseCase)
{
    $this->folderUseCase = $folderUseCase;
}

/**
 * @Route("/folders/", methods={"GET"})
 */
public function folders(): JsonResponse
{
    return new JsonResponse([
        'public' => $this->folderUseCase->getPublic(),
        'private' => $this->folderUseCase->getPrivate(),
        'other' => $this->folderUseCase->getOther()
    ]);
}

Partons du fait que nos dossier sont des informations que nous irions récupérer directement dans le Filesystem de l’application. Dans ce cas, côté UseCase, on pourrait écrire

private const FOLDER_TYPE_PUBLIC = 1;
private const FOLDER_TYPE_PRIVATE = 2;
private const FOLDER_TYPE_OTHER = 3;

private const FOLDER_TYPES = [
    self::FOLDER_TYPE_PUBLIC,
    self::FOLDER_TYPE_PRIVATE,
    self::FOLDER_TYPE_OTHER
];
    
private function getFolder(int $folderType): string
{
    if (! in_array($folderType, self::FOLDER_TYPES)) {
        throw new UnauthorizedHttpException('Provided folder type (' . $folderType . '.) is unknown');
    }

    $folderPath = __DIR__ . $folderType;
    if (!file_exists($folderPath)) {
        mkdir("folder/" . $folderPath);
    }

    return $folderPath;
}

public function getPublic(): string
{
    return $this->getFolder(self::FOLDER_TYPE_PUBLIC);
}

public function getPrivate(): string
{
    return $this->getFolder(self::FOLDER_TYPE_PRIVATE);
}

public function getOther(): string
{
    return $this->getFolder(self::FOLDER_TYPE_OTHER);
}

Voilà, on a globalement ce qu’il nous faut pour que notre petit exemple tourne correctement. Imaginez que ça ne fonctionne pas bien, et que vous vouliez afficher des variables dans votre code, comment feriez-vous ? un echo ? Mouais, ça pourrait fonctionner dans le UseCase. Sauf qu’essayez de le faire dans votre Controller et vous aurez une petite surprise : En effet, si on regarde la signature de la fonction :

public function folders(): JsonResponse

On s’aperçoit que le type de retour a été défini comme étant une JsonResponse, ce qui en soi est tout à fait logique pour un retour d’API. Cependant, que fait la fonction echo ? Elle demande à PHP de renvoyer une réponse, et donc modifie les Headers. Vous aurez donc une erreur de CORS, vous signalant que la réponse que vous essayez d’envoyer avec le echo, n’est pas conforme à celle définie dans votre signature. Mais alors, comment on va faire pour pouvoir afficher les informations que l’on veut ? (Je pense que vous devinez, non ?)

Place au debugger

Pour introduire assez rapidement le concept de debugger, il s’agit tout simplement d’un logiciel dont le but et de déboguer un programme, donc d’y chercher et corriger les fautes et les erreurs. Il en existe pour beaucoup de langages, et dans notre cas, celui qui nous intéressera pour PHP est Xdebug.

Pour que votre debugger fonctionne correctement, veuillez bien vous assurer que Xdebug est installé et activé sur votre machine. Un simple

php --version

vous permettra de vous en assurer, la réponse de cette commande vous affichant si vous utilisez ou non Xdebug dans votre configuration de PHP. Exemple :

PHP 7.4.13 (cli) (built: Nov 28 2020 06:24:43) ( NTS )
Copyright (c) The PHP Group
Zend Engine v3.4.0, Copyright (c) Zend Technologies
    with Zend OPcache v7.4.13, Copyright (c), by Zend Technologies
    with Xdebug v2.9.8, Copyright (c) 2002-2020, by Derick Rethans

Il est nécessaire de faire maintenant comprendre à PHPStorm que vous voulez utiliser le debugger, et de ce fait un pont doit être fait entre les deux pour que la magie opère. Pour y parvenir, nous allons tout d’abord cliquer sur le bouton « ADD CONFIGURATION…« , en haut à droite de votrre fenêtre :

Nous sommes à présent arrivés sur le fenêtre qui permet de lister et créer des configurations de debugger. Nous allons à l’aide du bouton « + » en haut à gauche, en créer un pour notre application PHP. Une liste de configuration s’affiche. Vous noterez que beaucouup de choix sont possibles, le debugger n’est donc pas quelcque chose de propre au PHP, mais bien un outil qui peut être utilisé sur n’importe quel langage, pourvu qu’un logiciel de debug soit fourni avec. Revenons à nos moutons, et choisissons « PHP Web Page » :

Trois informations vont être à remplir pour que la configuration soit complète :

• le nom du debugger (mettez ce que vous voulez)
• l’URL d’accès à votre application (le lien du localhost que vous avez défini)
• le serveur sur lequel le débugger doit s’exécuter

Concernant cette dernière étape, nous allons donc devoir déclarer un nouveau serveur. Cliquez donc sur le bouton « … » à côté de la ligne « Server ». Nous arrivons maintenant sur une nouvelle fenêtre. Une Déclarez le nom que vous voulez pour votre serveur, ainsi que l’URL d’accès à votre application. Si votre configuration Docker utilise un mapping de volumes pour faire le lien entre votre container applicatif et votre système de ficher :

volumes:
      - ./App:/var/www/html

vous aurez également besoin de déclarer cette liaison dans la configuration de votre serveur :

Maintenant que notre serveur est prêt, nous sommes de retour sur la configuration du debugger, avec tous les champs remplis. Appuyez sur le bouton « OK » en bas de page, et la configuration du de notre debugger est terminée. Nous sommes fin prêts pour la suite :

Utilisation du debugger

Maintenant que tout est configuré, revenons en haut à droite de votre fenêtre. Le debugger que nous venons de créer est automatiquement sélectionne, et les icônes sur la droite deviennent actives. Celle qui nous servira sera la deuxième : En cliquant dessus, votre navigateur s’ouvrira sur l’URL que vous avez définie dans l’écran précédent. PHPStorm et Xdebug sont donc maintenant en train d’écouter tout ce qu’il se passe sur le navigateur. Pour faire court, quand une requête est exécutée par PHP, Xdebug suit ce qu’i se passe, et va nous permettre d’aposer dans le code ce qu’on appelle des points d’arrêts. Ces derniers peuvent être mis sur toutes les lignes de votre code qui contiennent du PHP. Lorsque le code sera joué l’exécution se mettra en pause et vous aurez alors accès à tous le contexte d’exécution. Voyons comment ça fonctionne avec la capture suivante :

• en 1, sur la gauche de votre IDE, c’est là que vous pouvez mettre vos points d’arrêts. Le programme s’arrêtera sur chaque ligne qui en contient un.
• en 2, lorsque vous êtes arrêté sur une ligne de code, la chrononogie des méthodes et fichiers appelés depuis l’exécution du code s’affiche. En cliquant sur l’une d’elle vous pourrez vous diriger vers le fichier et remonter dans ce contexte.
• en 3, la liste des variables disponibles ainsi que leurs types et leurs valeurs sont présentes. On va pouvoir y retrouver :
  • les variables locales : par exemple ici $folderType
  • les variables de la classe courante : $this->…
  • les variables globales/superglobales : $_GET, $_POST, $_REQUEST…
• en 4, l’onglet des watches. Dans ce dernier, vous allez pouvoir suivre la valeur de toutes les variables ou expressions que vous voulez, tant qu’elle est disponible à ce moment d’exécution. Vous voyez que dans mon cas, je peux récupérer l’ID d’un user connecté, récupérer le validateur de Symfony. En bref, n’importe quelle expressions est accessible, et c’est bien là la grande force du debugger.
• la flèche verte sur la capture précédente est la barre d’outil du debugger. Plusieurs actions sont disponibles :
  • Redirige vers la ligne courante
  • Passe à la ligne suivante du même fichier
  • Rentre dans la fonction suivante
  • Force à rentrer dans la fonction suivante
  • Sors de la fonction
  • Joue le script jusque le curseur

Conclusion

Avec tous ces outils, vous avez maintenant la possibilité de visualiser toutes les variables dont vous avez besoin dans le cadre de votre debug, et également de naviguer ligne par ligne dans votre code, et ce lors de son exécution. Alors, convaincu d’abandonner le debug au echo, var_dump, dd et autres vieilleries ? 😁