17.2 Configurer le débogueur de PhpStorm sous Homestead

Il est impensable d'effectuer de la programmation de façon sérieuse sans disposer d'un débogueur adéquat. Heureusement, vous pourrez déboguer vos programmes Laravel sous PhpStorm grâce à Xdebug, une extension PHP.

Les instructions et impressions d'écran correspondent aux versions suivantes, qui étaient les plus récentes au moment lors de la dernière mise à jour de cet article (février 2019) :

• Laravel 5.7
• PHP 7.2.9
• PhpStorm 2018.3
• Homestead 7.0.0

Voici donc les étapes à réaliser.

Installation et configuration de XDebug

1. Vérifiez si Xdebug est installé sur votre machine virtuelle. Vous y parviendrez en entrant la commande suivante dans la méthode d'action correspondant à la racine de votre site Web (ex : PagesController@index).
   Contrôleur Laravel (PHP)

   phpinfo();

   Si vous ne voyez aucune référence à Xdebug, vous devez procéder à son installation.

   Normalement, avec Homestead, Xdebug devrait être déjà installé.

   Il peut cependant être désactivé, par exemple si la version de Homestead est configurée pour une version de PHP pour laquelle il n'y a pas de version stable de XDebug, comme c'était le cas en janvier 2018 avec Homestead 5.0.1 qui installe PHP 7.2 (les instructions pour l'activer sont présentées plus loin).

   Si Xdebug n'est pas installé, vous devrez procéder à son installation manuellement. Rappel : vous ne devriez normalement pas avoir à faire ceci :

   • https://laracasts.com/discuss/channels/servers/debugging-dont-work-anymore-with-homestead-php7-and-phpstrom

     ou

   • https://laracasts.com/discuss/channels/laravel/how-to-set-up-phpstormlatest-homestead-php7-xdebug?page=1
2. Pour savoir si PhpStorm voit Xdebug, allez dans le menu Run / Web Server Debug Validation. Le Path pointera vers le dossier public de votre projet puisque c'est la racine du site Web (sous Windows : C:\Users\monnom\Documents\CodeLaravel\monprojet\public et sous Mac : /Users/monnom/Documents/CodeLaravel/monprojet/public). L'URL sera celui que vous avez configuré dans le fichier hosts (attention : pas de 127.0.0.1 devant monprojet.test).

   Notez que le message « Remote host is configured as 'localhost' despite server host is probably not local » est normal.

   

3. Si vous obtenez un message du genre « No debug extension is loaded », c'est peut-être parce que vous devez activer Xdebug.
   • Vous devez d'abord créer un lien vers le fichier de configuration de Xdebug :
     Console Vagrant SSH

     sudo ln -s /etc/php/7.2/mods-available/xdebug.ini /etc/php/7.2/fpm/conf.d/20-xdebug.ini

     Vous pouvez maintenant activer l'extension.
     Console Vagrant SSH

     sudo phpenmod xdebug

4. Si vous voyez le message « Remote debug is not enabled », ceci indique que sur votre ordinateur, le débogage à distance n'est pas activé. PhpStorm donne même la solution pour régler le problème. Voici donc comment mettre cette solution en oeuvre :
   • Le fichier php.ini peut avoir été éclaté en plusieurs fichiers. C'est le cas ici. Les configurations de débogage sont dans le fichier etc\php7.2\fpm\conf.d\20-xdebug.ini. Notez que la version de PHP (ici : 7.2) pourrait être différente selon votre installation.

     Pour voir le contenu de ce fichier, exécutez les commandes suivantes dans la console Vagrant SSH :

     Console Vagrant SSH

     cd /etc/php/7.2/fpm/conf.d

     cat 20-xdebug.ini

   • Si la ligne xdebug.remote_enable=1 n'est pas présente, vous devez l'ajouter. On en profitera pour ajouter une série de configurations qui assureront que le débogueur fonctionnerra comme souhaité :
     Console Vagrant SSH

     sudo vim 20-xdebug.ini

     Et dans Vim, appuyez sur Insert puis entrez les configurations suivantes :

     Fichier xdebug.ini

     zend_extension=xdebug.so

     xdebug.default_enable=1

     xdebug.remote_enable=1

     xdebug.remote_port=9000

     xdebug.remote_autostart=1

     xdebug.remote_connect_back=1

     xdebug.remote_log = ~/xdebug.log

     Pour terminer votre saisie et enregistrer les modifications, appuyez sur ESCAPE puis la séquence de touches : w q (sans espaces entre les touches).

   • Vous devez maintenant redémarrer le service. Pour connaître la liste des services :
     Console Vagrant SSH

     service --status-all

     On recherche un service en lien avec PHP. On voit que le service s'appelle php7.2-fpm (le nom pourrait être différent selon votre installation PHP). Donc, pour redémarrer le service :

     Console Vagrant SSH

     service php7.2-fpm restart

     Si un mot de passe vous est demandé, entrez vagrant. Il s'agit du mot de passe que Homestead a créé pour l'usager vagrant sur votre Linux.

   • Une fois les configurations effectuées, faites à nouveau afficher la page Web contenant un appel à phpinfo(). Vous devriez voir les configurations de Xdebug, notamment xdebug.remote_enable qui est désormais à On.

     

     Remarquez que si vous allez dans PhpStorm, menu File / Settings / Languages & Frameworks / PHP (sous Windows) ou PhpStorm / Preferences / Languages & Frameworks / PHP (sous Mac) et que vous cliquez sur les points de suspension à côté de CLI Interpreter, vous devriez voir la mention «  Debugger: Not installed  ». Ceci est normal puisque cet écran montre les configurations pour un interpréteur CLI et que nos modifications ont été faites pour FPM.

Configurations dans PhpStorm

Une fois que XDebug est fonctionnel, il vous reste quelques configurations à faire dans PhpStorm.

• Allez dans le menu Files / Settings (Windows) ou PhpStorm / Preferences (Mac) puis puis choisissez l'option Languages & Frameworks / PHP / Servers.
• Vous devriez voir votre serveur Homestead dont le Host est monprojet.test (ou un autre nom de domaine selon ce que vous avez configuré). Ce serveur sera utilisé pour lancer l'application sans le débogueur. Vous devez créer un nouveau serveur en cliquant sur le +.
• Entrez à nouveau les informations qui étaient dans le premier serveur (Host : monprojet.test, Port : 80, Debugger : Xdebug) et nommez ce serveur HomesteadDebug et cette fois, vous devez cocher Use path mapping.
• À côté du dossier de votre projet (ex : C:\Users\monnom\Documents\CodeLaravel\monprojet sous Windows ou /Users/monnom/Documents/CodeLaravel/monprojet sous Mac), entrez le dossier de votre projet sur la machine virtuelle (ex : /home/vagrant/code/monprojet) puis appuyez sur Entrée.
• À côté du dossier public (ex : C:\Users\monnom\Documents\CodeLaravel\monprojet\public sous Windows ou /Users/monnom/Documents/CodeLaravel/monprojet/public sous Mac), entrez le dossier public sur la machine virtuelle (ex : /home/vagrant/code/monprojet/public) puis appuyez sur Entrée.

  

• Pour terminer, vous devez aller dans le menu Run / Edit Configurations puis ajouter une nouvelle configuration de type PHP Web Page qui utilise votre serveur de débogage. Nommez cette configuration Debug-Accueil.

  

• Vous pouvez désormais placer un point d'arrêt dans votre code, sélectionner la configuration de débogage dans le haut de la fenêtre puis cliquer sur l'icône de débogage pour lancer le débogage de votre application.