S’il y a bien un outil essentiel pour un développeur en dehors de son IDE, c’est son debugger (si vous n’en êtes encore convaincu, l’essayer, c’est l’adopter).
Pour PHP, le debugger utilisé par la majorité des développeurs est Xdebug. Lorsque vous développez localement avec PHP installé directement sur votre machine sa configuration est relativement simple.
Xdebug et Docker
Les choses se compliquent légèrement lorsque vous souhaitez utiliser Xdebug avec Docker. En effet, Docker rajoutant une couche d’abstraction supplémentaire entre votre machine et PHP, Xdebug considère que ce n’est plus de debugging local mais distant.
Xdebug propose deux types de configurations pour du debugging distant, via les options suivantes :
- xdebug.remote_connect_back
- xdebug.remote_host
remote_connect_back vs remote_host
xdebug.remote_connect_back prend pour valeur un booléen pour activer ou non ce paramètre. Si actif, Xdebug essaiera de se connecter au client ayant émis la requête HTTP.
xdebug.remote_host prend pour valeur l’IP du client souhaitant debugger. La session de debugging ayant lieu localement, sur votre machine, l’IP locale à laquelle vous pensez instinctivement est 127.0.0.1. Essayez, ça ne fonctionnera pas. La subtilité vient du fait que Xdebug va écouter toutes les IPs de votre réseau et s’attend donc à voir votre IP interne (telle qu’apparaissant sur votre réseau) plutôt que l’IP locale.
L’IP interne de votre machine étant susceptible de changer en fonction du réseau ou du changement de bail DHCP, xdebug.remote_connect_back semble bien plus facile à configurer. Et c’est le cas, mais uniquement sous Linux !
Xdebug et Docker for Mac
Ayant récemment changé de machine pour passer d’un Thinkpad sous Xubuntu à un Macbook Pro sous Mac OS, je m’attendais à faire face à quelques difficultés avec Docker, celui-ci tournant nativement sous Linux uniquement. Pour Mac OS et Windows il existe Docker for Windows et Docker for Mac qui embarquent, en plus de Docker, une machine virtuelle.
Lorsque j’ai voulu debugger un projet existant en gardant la même configuration de Docker et Xdebug sur mon Mac, forcément ça n’a pas fonctionné.
En parcourant Github, le forum officiel et Stackoverflow on découvre que peu de choix sont disponibles pour configurer Xdebug avec Docker for Mac et que ceux-ci se révèlent plutôt pénibles à l’utilisation :
- Définir un alias vers l’interface réseau utilisée afin d’obtenir une IP statique ;
- Configurer xdebug.remote_host avec une variable d’environnement et définir un script bash démarrant Docker (ou docker-compose) et mettant à jour la variable d’environnement avec votre IP actuelle.
Heureusement pour nous, depuis Docker for Mac 18.03 (sortie fin mars) le DNS « host.docker.internal » fait son apparition. Comme vous vous en doutez, cet hostname fait référence à l’IP interne de votre machine.
Il suffit tout simplement de configurer xdebug.remote_host avec pour valeur « host.docker.internal » et le tour est joué (attention, xdebug.remote_host implique que le paramètre xdebug.remote_connect_back soit désactivé) !
Configuration finale
Une configuration fonctionnelle pour debugger PHP avec Xdebug sous Docker for Mac pourrait ressembler à celle-ci :
xdebug.remote_enable = 1 xdebug.remote_autostart = 1 xdebug.remote_connect_back = 0 xdebug.remote_host = host.docker.internal xdebug.remote_idekey = PHPSTORM xdebug.remote_log = /var/log/xdebug_remote.log
