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:
- La instalación y configuración del lado del servidor.
- 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:
- Contar con una imagen basada en un
Dockerfileque incluya la instalación de XDebug - Tener instalada la extensión de debugging con PHP en VS Code
- Configurar correctamente el mapeo de directorios en la configuración de lanzamiento (
launch.json) - Tener la definición de
extra_hostsdel contenedor que tiene php apuntando ahost-gateway - Tener el xdebug correctamente configurado dentro del contenedor de php
