Siguiendo la entrega anterior, quiero compartir más pautas para depurar migraciones en Drupal. Si entonces tratamos módulos, plugins y gestión de objetos de configuración, ahora me apetece detenerme en algo más orientado al código. He elegido explicar cómo configurar Xdebug en un IDE —en este caso PhpStorm— para migraciones ejecutadas en una instalación local de Drupal con DDEV. Aunque el procedimiento es transversal y también sirve para otros desarrollos, lo aplicaremos a una migración. Esta es la quinta entrega de la serie. Espero que te resulte útil.

Foto de Unsplash, de Neenu Vimalkumar, @dreamquest12610

Índice

• 1. Introducción a Xdebug
• 2. Xdebug en DDEV
• 3. Configurar el IDE paso a paso
• 4. Errores al ejecutar Drush en contenedores
• 5. :wq!

1. Introducción a Xdebug

Vamos a complementar las técnicas de la entrega anterior. Ya sabemos revisar archivos de configuración y utilizar plugins de proceso para obtener información. Ahora añadiremos la tercera pieza: depurar una migración desde el código que interviene en ella, siguiendo las clases PHP que hacen funcionar todo el mecanismo.

Xdebug es una extensión clásica de PHP que permite, entre otras cosas, seguir las variables y observar sus valores durante la ejecución del software. No explicaremos aquí su instalación y administración general; nos centraremos en un caso concreto. Para desplegar Drupal localmente y probar las migraciones podemos usar DDEV, una herramienta basada en contenedores Docker que ya incluye Xdebug preparado para utilizarlo.

DDEV evita tener que montar un entorno LAMP clásico: organiza redes de contenedores preconfigurados con las herramientas de desarrollo, incluido Xdebug. Encontrarás más información, artículos y recursos en awesome-ddev.

2. Xdebug en DDEV

Si partimos de un entorno DDEV, podemos activar Xdebug de dos maneras.

La primera es editar config.yaml, en your_project/.ddev/config.yaml, y activar Xdebug. En el archivo mostrado en la captura, la opción aparece en la línea 9:

La segunda es utilizar los comandos de DDEV desde fuera del contenedor:

ddev exec enable_xdebug
ddev exec disable_xdebug

O también:

ddev xdebug
ddev xdebug on
ddev xdebug off

Estos comandos permiten activar y desactivar el recurso. Por rendimiento, Xdebug está desactivado inicialmente. Como trabaja del lado del servidor, ya se encuentra en el contenedor web y, en este escenario, nos queda preparar el IDE.

En esencia, los IDE funcionan de forma parecida con Xdebug: escuchan en un puerto y reaccionan al recibir una conexión. En la configuración descrita en el artículo original, Xdebug utiliza habitualmente el puerto 9000. Puedes consultar ejemplos de configuración en:

• Depuración paso a paso con DDEV y Xdebug.
• Xdebug desde la línea de comandos con DDEV.

El equipo de PhpStorm ya explicó la técnica básica en este artículo sobre depuración remota de scripts PHP de consola. Utilizaremos PhpStorm para el ejemplo.

3. Configurar el IDE paso a paso

Veremos los pasos básicos en PhpStorm, aunque el enfoque es similar en otros editores como VSCode. Al activar Xdebug queda disponible para los scripts PHP ejecutados desde la línea de comandos. Esto lo hace especialmente útil para depurar Drush o Drupal Console —la antigua y abandonada Drupal Console, por cierto—. DDEV facilita además su activación automática, lo que simplifica la depuración de nuestra migración.

Sigamos estos pasos:

1. Servidor del proyecto

Abre File → Settings → Languages & Frameworks → PHP → Servers y crea un servidor nuevo. Asígnale un nombre; utilizar el nombre del proyecto DDEV facilita reconocerlo. Indica el puerto 80 y selecciona Xdebug como depurador.

2. Configuración inicial

Cuando el servidor no es local para PhpStorm, necesitamos definirlo como servidor externo y establecer las correspondencias de archivos. En un entorno Docker o DDEV, el código se ejecuta dentro de un contenedor. DDEV sirve la instalación desde /var/www/html/, mientras que los archivos del equipo pueden estar en una ruta como /home/user/folder/projects/my_project. Configuraremos la correspondencia entre ambas rutas.

3. Escuchar conexiones de depuración

Activa el botón de escucha de conexiones de depuración del IDE.

4. Cargar una variable de entorno en el contenedor

Tenemos dos opciones. Podemos definirla para cada sesión entrando en el contenedor con ddev ssh y ejecutando allí:

export PHP_IDE_CONFIG="serverName=your.project.name.ddev.site"

También podemos establecerla de forma persistente mediante un archivo complementario docker-compose.env.yaml en .ddev/, junto a los demás archivos de configuración de Docker Compose:

version: '3.6'
services:
 web:
   environment:
     - PHP_IDE_CONFIG=serverName=your.project.name.ddev.site

Al detener y arrancar la red de contenedores con ddev stop y ddev start, este archivo se combinará con los demás y la variable se cargará automáticamente.

5. Puntos de interrupción

Podemos colocar puntos de interrupción en el código que interviene en la migración. Cuando un campo solo pasa del origen al destino, sin transformaciones, sabemos que se utiliza el plugin de proceso predeterminado: la clase Get.php, situada en /core/modules/migrate/src/Plugin/migrate/process/Get.php.

Es un buen lugar para detener algunos ejemplos de migración. Podemos añadir un punto de interrupción en transform(), que en la versión de la captura aparece en la línea 106:

4. Errores al ejecutar Drush en contenedores

Con el IDE escuchando y los puntos de interrupción preparados, al ejecutar Drush en DDEV puede aparecer un error de correspondencia de archivos. El motivo es que se está ejecutando el lanzador global de Drush del contenedor, instalado en /usr/local/bin/drush, en lugar del ejecutable del proyecto.

Tenemos dos opciones.

Podemos ejecutar Drush directamente desde el directorio vendor del proyecto, que ya está incluido en el mapeo de rutas del servidor remoto. El original muestra estas formas:

• Desde fuera del contenedor: ddev exec /vendor/bin/drush migrate-status.
• Desde dentro, tras ddev ssh: /vendor/bin/drush migrate-status.

La otra opción la recomienda Randy Fay, @randyfay, uno de los creadores de DDEV, en este comentario de una incidencia de GitHub.

Consiste en aprovechar el comando de ejemplo del archivo drush.example, en /your-name-project/.ddev/commands/web/, y sustituir la llamada a Drush por la ruta del ejecutable del proyecto: pasar de drush $@ a /var/www/html/vendor/bin/drush $@.

Así podemos depurar las migraciones con Xdebug en DDEV. Encontrarás más información en:

• Configuración de la depuración con PhpStorm.
• Incidencia 127 de docker4drupal.
• Incidencia 2341 de DDEV.

¡Ahora puedes ejecutar tu migración cómodamente! Lanza los comandos Drush de la migración, comprueba que se alcanzan los puntos de interrupción y empieza a seguir su ejecución.

5. :wq!

Canción recomendada