Configuración de Xdebug en PHPStorm

La depuración es uno de los procesos más importantes de la programación. Con la ayuda de un depurador se puede ver lo que ocurre en el programa, qué funciones se ejecutan, qué se almacena en variables, así como ejecutar todo paso a paso y entender exactamente en qué línea y en qué valores de variables se produce un error.

Por ejemplo, el depurador Xdebug se utiliza para PHP, PHPStorm es uno de los entornos de desarrollo más populares. A continuación vamos a ver cómo configurar Xdebug en PhpStorm para depuración en equipo local y en Docker.

Configurando XDEBUG en PHPSTORM

Hablemos de cómo se realiza la depuración en el servidor local.

Veamos todo el proceso usando Ubuntu y el intérprete PHP configurado con Apache como ejemplo. Para otras configuraciones las rutas de los archivos pueden ser diferentes, pero el punto es el mismo. El depurador Xdebug permite pausar la ejecución del código, ver la pila de llamadas y el contenido de las variables. Su única desventaja es que no hay una interfaz de control conveniente. Los IDE suelen utilizarse para gestionar la depuración. Pero el IDE no puede decirle al depurador que inicie la depuración porque sólo es responsable del código. Para ello necesitará la extensión de navegador Debug Helper, con cuya ayuda podrá activar el modo de depuración.

Primero necesitas instalar Xdebug. Para ello, ejecute:

$ sudo apt install xdebug

Una vez finalizado el proceso de instalación de Xdebug, debes configurar el programa para que al iniciar una sesión de depuración intente conectarse a nuestro IDE para controlar la depuración. Para ello, añade estas líneas al fichero /etc/php/7.4/apache2/conf.d/20-xdebug.ini en la versión Xdebug 2:

$ sudo vi /etc/php/7.4/apache2/conf.d/20-xdebug.ini
zend_extension=xdebug.so
xdebug.remote_enable=1
xdebug.remote_host=127.0.0.1
xdebug.remote_connect_back=1
xdebug.remote_port=9000
xdebug.remote_handler=dbgp
xdebug.remote_mode=req
xdebug.remote_autostart=false

Para una versión más reciente, es mejor utilizar un formato diferente:

xdebug.mode=debug
xdebug.start_with_request=trigger
xdebug.discover_client_host = false
xdebug.client_host = 127.0.0.1
xdebug.client_port = 9000

Echemos un vistazo más de cerca a la configuración. El primer parámetro xdebug.mode - modo de depuración, las opciones posibles son:

• develop - habilita la salida de información adicional, anula var_dump;

• debug - modo de ejecución de código línea por línea, es el modo que necesitamos en este caso;

• profile - creación de perfiles;

• trace - rastreo de la ejecución del programa.

Varios modos se activan simultáneamente cuando se enumeran entre comas. La segunda línea xdebug.start_with_request define cómo se iniciará el depurador para los modos debug, trace y similares:

• yes - siempre, al ejecutar scripts php;
• no - iniciar sólo desde código usando funciones especiales;
• trigger - a petición, usando una variable especial en $_ENV, $_POST, $COOKIE u otro array. Esta opción se ajusta mejor en este caso para que el depurador no se ejecute cuando no es necesario.

La tercera xdebug.discover_client_host se establece en true, en cuyo caso xdebug intenta conectarse al host pasado en la cabecera HTTP_X_FORWARDED_FOR. Dado que el host se especifica en la siguiente línea, esta característica no es necesaria en este caso. A continuación, el host cliente al que conectarse para el control de depuración es 127.0.0.1 y el puerto 9000. Este es el puerto por defecto utilizado en PhpStorm en este momento. Después de guardar la configuración, necesitas reiniciar Apache usando un comando especial:

$ sudo systemctl restart apache2

A continuación, debe configurar PhpStorm. Ejecute el programa, luego abra el menú Ejecutar -> Editar Configuraciones. Verás una ventana donde debes configurar el depurador.

Haz clic en el botón + y selecciona PHP Remote Debugger de la lista que se abre:

No cambies nada en la configuración, sólo especifica el nombre de este método de depuración. Si no especifica el servidor desde el que se esperan conexiones, se aceptarán todas las conexiones.

Si desea cambiar el puerto al que se conectará Xdebug, abra Archivo -> Configuración -> PHP -> Depuración -> DBGp Proxy. Aquí puede especificar el puerto deseado.

Podemos decir que ahora el IDE está listo. Ahora haga clic en el error en la barra de herramientas superior. El programa empezará a esperar a que el depurador se conecte y pondremos algunos puntos de interrupción en el código simplemente haciendo clic delante de la línea con el código:

Ahora sólo queda configurar el navegador.Para Chrome, puedes descargar una extensión especial. Instálala y abre la página que quieras depurar. Haz clic en el icono de la extensión y selecciona Depurar. El icono de la extensión se volverá verde:

Actualice la página y vuelva a PHPStorm. Si todo se ha hecho correctamente, se iniciará una sesión de depuración. En la primera ejecución, el programa puede pedirle que configure las rutas de los archivos locales para que coincidan con las rutas de los archivos remotos. Para el servidor local no es necesario configurar nada aquí, simplemente haga clic en Aceptar:

Después de eso el depurador detendrá la ejecución en el punto de interrupción seleccionado y la interfaz de depuración aparecerá en el programa:

Ahora vamos a entender cómo configurar Xdebug PhpStorm y Docker.

Depurando PHP en DOCKER

Docker puede ser un poco complicado. Dado que el depurador tiene que conectarse al propio IDE, necesitas reenviar el host al contenedor. En Windows, esto se puede hacer usando la dirección host.docker.internal. Pero en Linux, esto no ocurre por defecto. Para añadir tal dirección necesitas añadir las siguientes líneas a docker-compose:

extra_hosts:

host.docker.internal: host-gateway

Utilizamos la siguiente estructura de directorios:

El docker-compose.yaml mínimo requerido tendrá este aspecto:

version: '3.5'
networks:
  losst-network:
services:
  nginx:
    image: nginx
    ports:
        - '8094:80'
    volumes:
        - ./www/:/var/www/
        - ./conf/nginx:/etc/nginx/conf.d
    networks:
        - losst-network
  php-fpm:
    build: 
      context: ./conf/php-fpm
    extra_hosts:
      host.docker.internal: host-gateway
    volumes:
      - ./www:/var/www/
    networks:
      - losst-network

Simplemente declaramos dos contenedores, nginx y php-fpm. En el primero no hacemos ningún cambio, por lo que basta con coger la imagen oficial, montar la carpeta fuente, el fichero de configuración y el port forward. En el segundo contenedor es necesario instalar y configurar Xdebug, por lo que habrá que construirlo sobre la base del contenedor php oficial. Para el mismo contenedor es necesario especificar la directiva extra_hosts, sin ella nada funcionará. La configuración de Nginx también es bastante estándar:

server {
  listen 80;
  server_name _ !default;
  root /var/www/;
  add_header X-Frame-Options "SAMEORIGIN";
  add_header X-XSS-Protection "1; mode=block";
  add_header X-Content-Type-Options "nosniff";
  index index.html index.htm index.php;
  charset utf-8;
  location / {
    try_files $uri $uri/ /index.php?$query_string;
  }
  error_page 404 /index.php;
  location ~ .php$ {
    fastcgi_pass php-fpm:9000;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
    include fastcgi_params;
  }
}

Así es como se configura el procesamiento de scripts PHP en el contenedor php-fpm, y redirigir URLs inexistentes a index.php, que es bastante estándar para muchos frameworks y CMS. En el Dockerfile del contenedor php-fpm, se ve así:

Instala xdebug usando pecl, y luego copia su archivo de configuración en el contenedor. Archivo:

xdebug.mode=debug
xdebug.start_with_request=trigger
xdebug.discover_client_host = false
xdebug.client_host = host.docker.internal
xdebug.client_port = 9000

Xdebug 3 para PHP 8 se instala en el contenedor, porque la versión antigua ya no funciona con esta versión del lenguaje, así que se utiliza la nueva sintaxis de configuración. Bien host, host.docker.internal, que antes se prescribía en docker-compose.yaml. La configuración del docker xdebug PHPStorm ya está completa. A continuación, puede ejecutar el proyecto:

docker-compose up --build

Ahora, al igual que en la opción anterior puede habilitar el modo de depuración en el navegador, actualizar la página y el depurador se conectará correctamente al IDE, a pesar de que se está ejecutando en Docker