Configurar Docker con xDebug y VS Code

Prerrequisitos

Como mínimo, debemos tener lo siguiente instalado en nuestro ordenador:

• Docker Compose: Guía de instalación en este link.
• El IDE de desarrollo visual studio code.
• Extensión de VS Code para debuguear en PHP, PHP Debug.

Pasos a seguir

Lo primero que debemos hacer, en la carpeta del proyecto, es crear un fichero llamado Dockerfile, este fichero es la imagen de Docker que define la configuración de nuestro contenedor, y tiene este código:

FROM php:7.3-apache

RUN pecl install -f xdebug \
&& echo "zend_extension=$(find /usr/local/lib/php/extensions/ -name xdebug.so)" > /usr/local/etc/php/conf.d/xdebug.ini;

Con esta línea: RUN pecl install -f xdebug \ && echo "zend_extension=$(find /usr/local/lib/php/extensions/ -name xdebug.so)" > /usr/local/etc/php/conf.d/xdebug.ini, le instalamos la extensión xDebug al PHP del contenedor de Docker cuando lo levantemos.

También en la raíz del proyecto vamos a crear el fichero que ejecutara la imagen de Docker que acabamos de crear, docker-compose.yml, con el siguiente contenido:

 version: '3'

 services:
   web:
    build:
        context: .
        dockerfile: ./Dockerfile
    environment:
        XDEBUG_CONFIG: remote_host=172.17.0.1 remote_port=9000 remote_enable=1
    ports:
        - '80:80'
    volumes:
        - './web:/var/www/html'

En este fichero lo que estamos haciendo es construir un contenedor de docker que tendrá un servidor Apache y la versión de PHP 7.3 con la extensión de xDebug ya instalada y configurada para poder conectar el servidor web con nuestro VS Code.

En esta línea: XDEBUG_CONFIG: remote_host=172.17.0.1 remote_port=9000 remote_enable=1 se configura el xDebug. Cambiar esto "172.17.0.1" por esto "host.docker.internal" en caso de usar Windows o Mac.

Una vez tengamos los dos ficheros, ejecutamos el comando que creara el contenedor de Docker:

    docker-compose up -d

Esto no debería tardar mucho y cuando nos salga algo como esto en nuestro terminal: Creating CONTAINER_NAME ... done, veremos que se ha creado una carpeta llamada web. En esa carpeta es donde debemos alojar el código de nuestra plataforma web. Es posible que debas actualizar los permisos de la carpeta para poder crear contenido.

Muy bien, ahora mismo tenemos mitad del camino hecho. El siguiente paso es en nuestro VS Code, ya que tenemos que configurar el xDebug.

La extensión mencionada en los prerrequisitos añadirá un icono a la derecha en nuestro IDE, al pulsarlo veremos el área de gestión de xDebug:

Al pulsar la tuerca pequeña de arriba, nos abre un launch.json que podremos editar. Este fichero contiene la configuración de la extensión PHP Debug, y en ella debemos editar el objeto de configurations, sustituyendo el código por el de más abajo, para que pueda conectarse al servidor del contenedor de Docker:

Sustituye PATH_FOLDER por tu estructura de carpetas

 "configurations": [
    {
        "name": "Listen for XDebug",
        "type": "php",
        "request": "launch",
        "port": 9000,
        "pathMappings": {
            "/var/www/html": "PATH_FOLDER/web"
        },
        "xdebugSettings": {
            "max_data": 65535,
            "show_hidden": 1,
            "max_children": 100,
            "max_depth": 5
        }
    }
   ]

Cuando hayamos editado este fichero, lo guardamos y vamos a la carpeta web para crear un fichero, index.php:

<?php
echo "hello world!"
?>

Y ponemos el punto de debug en el echo. Al abrir un navegador y poner la url http://localhost/, verás como automáticamente se abre tu VS Code con el código de tu index.php y la línea del echo marcada, normalmente con un subrayado amarillo. Esto quiere decir que la ejecución del código se ha parado en el punto de debug o de ruptura, como prefieras llamarlo. Ahora mismo ya tienes tu contenedor web de Docker con el xDebug configurado y conectado a tu VS Code.

En caso de que no te coja el punto de debug automáticamente, puedes activar el modo debug del VS Code pulsando en el triangulo de play verde que se ve en esa ventana del IDE.