XDebug con VSCode en Docker sobre Ubuntu

Usar Docker en proyectos PHP es un viaje de ida.

Olvidarse del «te juro que en mi casa andaba!» es una bendición.

Claro que, para poder desplegar, primero hay que desarrollar. Y desarrollar implica, claro está, debuggear.

En PHP no contamos con un debugger incorporado a nuestros IDEs… afortunadamente existe XDebug.

El problema, sin embargo, suele ser la configuración que depende de dos factores que deben combinarse:

1. La instalación y configuración del lado del servidor.
2. La configuración del IDE para poder utilizarlo.

Existen muchas combinaciones posibles para realizar esta tarea, cada una con sus pequeñas particularidades. En este artículo me enfocaré en una de las combinaciones más populares por estos días:

VSCode sobre Ubuntu con un WebServer montado en Docker.

La aplicación que usaré como ejemplo es el CRM de código abierto rukovoditel.

El Dockerfile

Lo primero será definir el archivo Dockerfile que permita contar con un servidor web que pueda ejecutar php y, a la vez, tenga instalado XDebug:

FROM php:7.4-apache
LABEL authors="mauro.chojrin@leewayweb.com"

RUN apt-get update && \
    apt-get install -y \
        libpng-dev \
        libzip-dev && \
        pecl install xdebug-3.1.6

RUN docker-php-ext-install gd && \
    docker-php-ext-install zip && \
    docker-php-ext-install mysqli && \
    docker-php-ext-enable xdebug

COPY xdebug.ini /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini

ADD app /var/www/html

RUN chown -R www-data.www-data /var/www/html

La configuración de XDebug

A continuación ha de crearse el archivo de configuración de xdebug (xdebug.ini) en la raíz del proyecto:

zend_extension=xdebug

[xdebug]
xdebug.mode=develop,debug
xdebug.client_host=host.docker.internal
xdebug.start_with_request=yes

El archivo docker-compose.yml

Posteriormente será el turno del archivo docker-compose.yml que contendrá los servicios necesarios para dar vida a la aplicación:

version: '3.1'
services:
  mysql:
    image: 'mysql:5.7.42-debian'
    environment:
      - MYSQL_ROOT_PASSWORD=root
      - MYSQL_DATABASE=ruko
      - MYSQL_USER=ruko
      - MYSQL_PASSWORD=ruko
    restart: always
  webserver:
    image: 'ruko_ws'
    build:
      context: '.'
    ports:
      - '8888:80'
    volumes:
      - './app:/var/www/html:rw'
      - './xdebug.ini:/usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini'
    extra_hosts:
      - host.docker.internal:host-gateway

Con esto está listo todo lo necesario del lado de la infraestructura.

Los siguientes pasos se darán del lado del host.

Configuración de VS Code

La extensión de debugging de PHP

Una vez abierto el proyecto, hay que asegurarse de tener instalada la extensión requerida para realizar debugging:

La configuración de lanzamiento

A continuación, debe crearse una configuración de lanzamiento para realizar el debugging:

De las múltiples entradas que encuentro la que interesa es la llamada Listen for Xdebug.

Por defecto, lo que se ve es:

{
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003
},

Lo que se necesita es agregar la definición del mapeo de directorios, desde el local al del servidor.

En este caso, el directorio en el servidor (en el contenedor Docker) es /var/www/html/, el cual debe ser conectado con el directorio app dentro de la raíz del proyecto.

Para usar el directorio del host, sin hardcodearlo, es posible usar la variable de VisualStudio workspaceFolder la cual contiene el directorio raíz del proyecto.

De modo que la configuración quedará de esta forma:

{
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
             "/var/www/html/": "${workspaceFolder}/app"
      }
},

Debuggeando

Con esto listo es posible arrancar el debugger:

Para ver su efecto es conveniente introducir un punto de interrupción (breakpoint) en algún lugar del código.

Tomemos como ejemplo el archivo app/install/index.php ya que es el primero que se ejecuta al ingresar a la aplicación.

Lo próximo será ir al navegador web, donde se dará comienzo a la sesión de debugging usando el asistente de XDebug.

Luego se debe ingresar la dirección de la página (http://localhost:8888 en este caso) y, al dar enter se abrirá automáticamente la ventana de VS Code:

Donde podrá ejecutarse el código paso a paso:

Inspeccionar variables en tiempo real

Y, en general, utilizar todos los servicios provistos por XDebug.

Puntos clave

En resúmen, las claves para hacer funcionar XDebug con VSCode en Docker sobre Ubuntu son:

1. Contar con una imagen basada en un Dockerfile que incluya la instalación de XDebug
2. Tener instalada la extensión de debugging con PHP en VS Code
3. Configurar correctamente el mapeo de directorios en la configuración de lanzamiento (launch.json)
4. Tener la definición de extra_hosts del contenedor que tiene php apuntando a host-gateway
5. Tener el xdebug correctamente configurado dentro del contenedor de php