Depurar con PhpStorm y Symfony en una imagen de Docker

Configuración de PHP/Docker

Si estás desarrollando con Symfony, instalado en un docker compose y aún no utilizas el depurador, entonces este artículo es para ti. Vamos a mostrarte cómo preparar tu entorno para que ya no tengas que hacer dd() o var_dump. Una vez que hayas experimentado las alegrías de depurar, no podrás prescindir de ello, ya que aumentará enormemente tu comodidad.

Para este artículo necesitas tener una aplicación Symfony alimentada por apache/php (o nginx y fpm, no importa) con un archivo docker-compose.yml

El primer paso es instalar xdebug y configurar tu entorno PHP. Si aún no lo has hecho, aquí tienes los elementos que debes tener instalados en tu Dockerfile.

RUN pecl install xdebug-3.1.6 && docker-php-ext-enable  xdebug;

Toma en cuenta que si estás utilizando PHP 8.1 necesitarás instalar la versión 3.2.0

RUN pecl install xdebug-3.2.0 && docker-php-ext-enable  xdebug;

Personalmente, configuro mi php.ini directamente copiando el archivo desde la construcción del Dockerfile.

COPY php.ini /usr/local/etc/php/conf.d/app.ini

Este es su contenido, siéntete libre de instalarlo como desees.

; conf/php.ini
date.timezone = Europe/Paris

opcache.enable = 1
opcache.enable_cli = 1
opcache.memory_consumption = 256
opcache.max_accelerated_files=20000
opcache.revalidate_freq = 0

upload_max_filesize = 16M
post_max_size = 16M

realpath_cache_size = 4096k
realpath_cache_ttl=600

display_errors = Off
display_startup_errors = Off
max_execution_time=5000
memory_limit = -1

xdebug.mode=debug,develop,trace
xdebug.idekey=docker
xdebug.start_with_request=yes
xdebug.log=/dev/stdout
xdebug.log_level=0
xdebug.client_port=9003
xdebug.client_host=host.docker.internal

Fíjate en la parte entera de xdebug del archivo. Esto es importante para el correcto funcionamiento del resto de este artículo. El modo nos permite indicarle a xdebug las opciones que necesitamos.

develop: Esto te dará un var_dump mejorado en tu aplicación pero también información adicional sobre advertencias, avisos. Más información aquí: https://xdebug.org/docs/develop

debug: Esto te permitirá usar step debug, establecer puntos de interrupción y avanzar a través del código línea por línea.

trace: Registra todas las llamadas a funciones, asignaciones de variables... ¡todo! Es exigente pero no importa.

idekey: Es la clave enviada por xdebug para decirle a PhpStorm '¡eh, estoy depurando esta aplicación, úsame!'

client_port: El puerto al cual se envía el zócalo de conexión de la sesión de depuración.

client_host: Esta es la IP a la cual enviamos nuestra conexión para la inicialización de nuestra sesión de depuración. Estamos usando Docker así que especificaremos cómo salir de nuestro entorno docker para atacar al host en nuestra máquina Linux.

Una vez que tu docker esté bien, deberías tener esto en tu entorno PHP:

Aquí hay un ejemplo de un docker-compose:

version: "3.8"
services:
  php-7.3:
    image: 'devpartitech/php:7.3-apache'
    ports:
      - "80:80"
    volumes:
      - "./:/var/www/"
    extra_hosts:
      - host.docker.internal:host-gateway

No continúes con el siguiente paso hasta que hayas validado esta etapa.

Configuración de PhpStorm

¡Bien! Tenemos nuestro entorno Docker configurado con una página Symfony. Vamos a configurar PhpStorm para poder recibir la sesión de debug.

Abre la configuración de PhpStorm.

Si aún no lo has hecho, instala el plugin de Symfony.

Bajo el menú PHP tienes los menús de Debug.

En el primer menú especifica a tu IDE que debe escuchar el puerto 9003. Puedes cambiar el puerto si lo deseas, pero también necesitará ser especificado en el php.ini.

Bajo el menú de Plantillas coloca el enlace al directorio Symfony var/cache. No pongas la ruta que está en tu contenedor. Se trata de la ruta en tu disco (tu máquina, en mi caso Ubuntu). Sin esto, el IDE no será capaz de usar puntos de interrupción en tus plantillas TWIG.

Bajo el menú de Proxy DBGp:

Recuerda la ide key y el puerto de antes.

Bajo el menú de Servidores, crea un nuevo servidor haciendo clic en el "+".

Una vez que tu servidor web esté especificado finalmente podemos probar el depurador de PhpStorm!

Para probar puedes ir a cualquier Controlador y plantilla y poner puntos de interrupción. Para hacer esto haz clic en el margen (donde tienes los números de línea).

Haz clic en el pequeño "bug" en la parte superior de tu IDE

Debería cambiar al modo "escuchando"

Refresca tu página web y deberías tener acceso a las opciones de depuración 😊

¡Y eso es todo!