Configuración Docker + Xdebug en un entorno MacOS

Programar sin debugar debería estar prohibido para cualquier desarrollador que se precie. El problema es que a veces no nos lo ponen fàcil, y ese es el caso de docker en MacOS. Después de una dura batalla, hemos conseguido hacer funcionar xdebug en docker y poder debugar con PhpStorm. En este artículo os detallamos toda la configuración necesaria para poner dicho entorno en funcionamiento.

1. Fichero docker-compose.yml

En el lado de Docker, el contenido del fichero docker-compose.yml deberá contener lo siguiente, por debajo del bloque php – environment:

PHP_XDEBUG: 1
PHP_XDEBUG_MODE: debug,develop
PHP_IDE_CONFIG: serverName=my-ide
PHP_XDEBUG_IDEKEY: "PHPSTORM"
PHP_XDEBUG_CLIENT_HOST: host.docker.internal
PHP_XDEBUG_CLIENT_PORT: 9003
PHP_XDEBUG_REMOTE_AUTOSTART: 1
PHP_XDEBUG_REMOTE_CONNECT_BACK: 0
PHP_XDEBUG_START_WITH_REQUEST: 1

PHP_XDEBUG_IDEKEY  variará en función de nuestro IDE favorito para desarrollar. En este ejemplo hemos usado PhpStorm, de ahí ese valor. Por ejemplo, para Visual Studio Code seria “VSCODE”.

En al versión 3 de xdebug se usa el puerto 9003 por defecto, mientras que en la versión 2 era el 9000. Este setting, PHP_XDEBUG_CLIENT_PORT, sería redundante, pero por la paranoia prefiero que esté presente y descartar errores por esta causa.

En el campo PHP_IDE_CONFIG: serverName  podemos poner cualquier nombre, y lo necesitaremos posteriormente cuando hagamos la configuración del lado de PhpStorm, ya que es el nombre del servidor que va en el “IDE”.

Por último, comentar el PHP_XDEBUG_MODE , que admite diferentes valores como debug, develop, trace, profile… puedes consultar una lista detallada de los posibles valores de esta y otras variables en https://xdebug.org/docs/all_settings.

2. Configuración /etc/hosts

Este paso no existe en la mayoría de tutoriales que hemos seguido en nuestro aprendizaje, y es un paso básico. El setting PHP_XDEBUG_CLIENT_HOST  tiene por defecto para Mac el valor "host.docker.internal”, ya que asume que en nuestro fichero de hosts tenemos esta entrada definida apuntando a nuestra máquina (127.0.0.1). En nuestro caso, por alguna razón desconocida, no teníamos esta entrada, y al añadirla se resolvieron muchos problemas. Así que, si no está, añade:

127.0.0.1 host.docker.internal

3. Configuración en PhpStorm

Una vez llegados aquí, si tu docker arranca correctamente con docker compose up -d, llega el momento de configurar el IDE para que se conecte al docker, que en nuestro caso será PhpStorm.

En nuestro proyecto, vamos a Run -> Edit configurations:

Añadimos una configuración de tipo PHP Web Page a partir de la plantilla, lo nombramos como queramos y vamos a configurar el servidor, que es la parte importante. Si hacemos clic en los […] podremos configurar el servidor, y veremos algo así:

Lo importante de esta pantalla es el nombre del Host, que debe ser igual a lo que pusimos en el docker-compose.yml, en este caso el famoso “my-ide”. Respecto al puerto, aunque nuestro docker funciona en el puerto 8000, aquí hay que poner 80.

Finalmente está el tema de los mapeos, no menos importante. No hace falta configurar mapeos fichero a fichero, pero sí por lo menos de la carpeta superior. Es decir, si en nuestro sistema de archivos local el proyecto está en /Users/[user]/Sites/mi_web_molona, habrá que decirle a PhpStorm la ruta remota en docker, por ejemplo /var/www/html.