Xdebug con PHP8.2, Docker, Nginx y PHPStorm

¿Eres de esas personas que usan print_r(), var_dump() o dump() para buscar fallos en tus aplicaciones?

Pues que sepas que hay otras opciones mejores, como Xdebug. Xdebug te permite ejecutar paso a paso un script para ver qué está pasando en cada línea de tu código.

Hoy vamos a ver cómo poner en marcha un entorno con las siguientes cosas:

• PHP8.2.
• Nginx
• Docker.

Y vamos a usar como IDE mi querido PHPStorm.

El primer paso es montarnos una estructura de directorios como ésta:

• docker:
  • nginx:
    • default.conf
  • php
    • conf.d
      • error_reporting.ini
      • xdebug.ini
    • Dockerfile
• src:
  • index.php
• docker-compose.yml

docker-compose.yml

Vamos a empezar por el fichero que junta todas las demás piezas, el docker-compose.yml:

version: '3'

services:

  webserver:
    image: nginx:latest
    ports:
      - 80:80
    volumes:
      - ./docker/nginx/default.conf:/etc/nginx/conf.d/default.conf
      - ./src:/var/www/html

  php-fpm:
    build: ./docker/php/
    expose:
      - 9000
    volumes:
      - ./src:/var/www/html
      - ./docker/php/conf.d/xdebug.ini:/usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
      - ./docker/php/conf.d/error_reporting.ini:/usr/local/etc/php/conf.d/error_reporting.ini

Aquí tenemos dos secciones importantes:

• webserver: este es el servidor Nginx que va a funcionar con el puerto 80.
• php-fpm: este va a ser el PHP del que va a hacer uso el servidor Nginx.

Servidor Nginx

Para el Nginx vamos a usar un paquete oficial: el nginx:latest y vamos a personalizarlo usando el siguiente fichero de configuración:

server {
    index index.php index.html;
    server_name phpfpm.local;
    error_log  /var/log/nginx/error.log;
    access_log /var/log/nginx/access.log;
    root /var/www/html;
    location ~ \.php$ {
        try_files $uri =404;
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_pass php-fpm:9000;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param PATH_INFO $fastcgi_path_info;
    }
}

Este fichero debe ir dentro de la carpeta: docker/nginx.

PHP-fpm

Para el PHP-fpm vamos a usar un paquete personalizado que vamos a construir a continuación.

Crea el siguiente fichero Dockerfile dentro de docker/php:

FROM php:8.2-fpm

RUN pecl install xdebug \
    && docker-php-ext-enable xdebug

Vamos a partir de un paquete preconfigurado llamado php:8.2-fpm al que vamos a añadir la extensión Xdebug.

Nota: me han contado recientemente que ahora se lleva más llamar Containerfila el fichero Dockerfile.

Vamos a añadir un par de ficheros en la carpeta docker/php/conf.d que usaremos en el docker-compose.yml.

Por un lado tenemos el fichero error_reporting.ini:

error_reporting=E_ALL

Y por otro el fichero xdebug.ini:

zend_extension=xdebug

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

Según mi experiencia si no añades la línea «xdebug.discover_client_host = 1» no funciona todo el invento éste porque no se comunica con el IDE.

Nuestra aplicación

Y luego ya podemos meter nuestra aplicación dentro de la carpeta «src». Si quieres meterlo en otra carpeta tendrás que retocar el docker-compose.yml donde dice:

- ./src:/var/www/html

Poner todo en marcha

Lo siguiente es irnos a la raíz del proyecto, donde está el fichero docker-file.yml y ejecutar el comando:

$ docker-compose up --build

La opción –build es importante para construir la imagen de PHP-fpm. Tendremos que añadir esta opción cada vez que modifiquemos el fichero Dockerfile.

PHPStorm

El último paso sería configurar PHP-Storm para que se conecte a nuestro contenedor con Xdebug.

Nos vamos a File -> Settings -> PHP -> Debug y modificamos el puerto:

Ponemos el puerto 9003. Se recomienda también marcar la casilla «Break at first line in PHP scripts» para probar que todo está bien. Luego la podemos quitar.

Lo siguiente es decirle a PHPStorm que «escuche» a conexiones de Debug (es el icono que parece un teléfono con un bicho):

Y por último solo nos queda irnos al navegador y teclear:

http://localhost

Si todo ha ido bien tendremos una sesión de debug abierta en PHPStorm.

---

¿Sabes lo que es el reto de PHP?

He creado el PHP Journey, una plataforma para que recibas de forma gratuita un email cada día con una pequeña perla de sabiduría de PHP y una pregunta que deberás responder.

Cada día pones a prueba tus conocimientos y aprendes algo nuevo.

Apúntate aquí:

https://urlantools.urlanheat.com/newsletter/php-journey/subscribe

---