Cómo usar XDebug en proyectos de WordPress.com Studio

Una de las necesidades más comunes durante el desarrollo de plugins en WordPress.com Studio es poder depurar código PHP con precisión. Aunque Studio aún no ofrece soporte oficial para XDebug, existe una forma efectiva de activarlo puntualmente si lo necesitamos en nuestro proyecto de Studio utilizando wp-env.

Si bien wp-env nos permite activar XDebug para depurar el código de un plugin, perdemos el rastro del código cuando el error está dentro de los archivos de WordPress Core ya que estos se ejecutan dentro de contenedores Docker. La visibilidad de los archivos de WordPress que nos ofrece Studio la perdemos un poco al utilizar wp-env.

La técnica explicada en este artículo permite conectar XDebug con tu editor local (como Cursor o VS Code) y hacer debugging interactivo, tanto en el código de tu plugin como en el código de WordPress de tu proyecto en Studio. Todo esto, mapeando correctamente el entorno interno del contenedor al sistema de archivos local.

Esta técnica me la comentó Ryan Welcher hace unas semanas y me pareció super interesante. La explica paso a paso en este video:

El soporte nativo para XDebug en Studio aún no está diponible pero está en el roadmap. Puedes seguir el progreso en esta issue: Automattic/studio#192

Tabla de Contenidos

¿Por qué usar XDebug en proyectos Studio?

Cuando desarrollas un plugin dentro de un entorno WordPress.com Studio, es frecuente encontrarse con errores que no siempre se reflejan claramente en los logs o en el navegador. Con XDebug puedes:

Detener la ejecución en cualquier línea del código PHP.
Inspeccionar variables y estructuras internas.
Ver la pila de llamadas (stack trace) en tiempo real.
Depurar hooks, filtros, respuestas de la REST API, o lógica de templates.

Por ejemplo, puedes colocar un breakpoint dentro de un callback de rest_api_init, o en una función que registre una acción en init, y ver con detalle qué está ocurriendo.

¿Cómo puedo depurar mi código sin XDebug?

También puedes depurar en Studio utilizando herramientas clásicas como var_dump() o error_log(), que siguen siendo muy útiles en casos simples o cuando XDebug no está configurado.

WordPress proporciona una guía completa sobre cómo habilitar y usar el modo de depuración:
🔗 Depurar WordPress – developer.wordpress.org

Cómo activar el log de errores en Studio

Abre o crea el archivo wp-config.php en tu proyecto.
Añade las siguientes líneas si no existen:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

Esto activará el modo de depuración y guardará los mensajes en un archivo en lugar de mostrarlos en pantalla.

Cómo escribir en el log

Desde tu plugin o tema puedes hacer:

error_log( 'Este es un mensaje de prueba desde mi-plugin.' );

¿Dónde se guarda el archivo de logs?

Por defecto los mensajes se guardan en:

/wp-content/debug.log

Puedes abrir ese archivo manualmente para revisar los mensajes de error y depuración. También puedes monitorearlo en tiempo real con:

tail -f .wp-env/wordpress/wp-content/debug.log

Si realmente necesitas XDebug en tu proyecto Studio puedes aprovechar wp-env puntualmente para ello.

Depurando proyectos de WordPress.com Studio con `wp-env` y XDebug

Paso 1: Abre el plugin como proyecto independiente

Abre el plugin en el que estás trabajando en un espacio de trabajo individual dentro de Cursor o VS Code. Esto permite que la configuración de depuración sea específica al plugin.

Por ejemplo:

~/STUDIO/mi-sitio-studio/wp-content/plugins/mi-plugin-personalizado

Abre esta carpeta directamente como raíz del proyecto en el IDE.

Paso 2: Crea el archivo `.vscode/launch.json`

En la raíz del plugin, crea la carpeta .vscode (si no existe) y dentro un archivo launch.json con el siguiente contenido:

{
  "configurations": [
    {
      "name": "Listen for XDebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/var/www/html/": "${userHome}/STUDIO/mi-sitio-studio"
      }
    }
  ]
}

🔁 Importante: Asegúrate de reemplazar ${userHome}/STUDIO/mi-sitio-studio con la ruta real completa a tu proyecto Studio local.

Este archivo indica a tu editor cómo traducir las rutas dentro del contenedor de Docker (/var/www/html/) a las rutas reales en tu sistema de archivos local. Sin esto, los breakpoints no funcionarán correctamente.

Paso 3: Inicia el entorno con XDebug activado

Desde la terminal, dentro de la carpeta del plugin, ejecuta:

wp-env start --xdebug

⚠️ Este comando asume que:

Tienes wp-env instalado globalmente:

  npm install -g @wordpress/env

Y que Docker está en marcha, ya que wp-env utiliza contenedores Docker para levantar el entorno. Si Docker no está activo, wp-env no podrá iniciar correctamente.

Una vez lanzado el entorno, XDebug quedará activado y escuchando en el puerto 9003, listo para recibir conexiones desde tu editor.

Paso 4: Coloca breakpoints y comienza a depurar

En Cursor, una vez que tu entorno wp-env está corriendo con XDebug, haz lo siguiente:

Coloca breakpoints en el código PHP (haz clic a la izquierda del número de línea).
Abre el menú de ejecución (ícono ▶️ en la esquina superior izquierda) y selecciona “Listen for XDebug”.
Visita en tu navegador una URL que ejecute el código que contiene el breakpoint.
Cursor detendrá la ejecución automáticamente y te mostrará el estado del programa, variables locales y la pila de llamadas.

💡 Esto te permite seguir paso a paso la lógica de ejecución, incluso si el error ocurre dentro del código núcleo de WordPress.

Paso 5: Captura errores y avisos automáticamente

Asegúrate de que tu entorno de depuración esté configurado para detener la ejecución en:

Excepciones (Exception)
Warnings (E_WARNING)
Notices (E_NOTICE)

Esto no solo se aplica al código de tu plugin, sino también al resto del código de la instalación WordPress que forma parte del entorno wp-env de Studio.

Esto significa que incluso si el error ocurre dentro del núcleo de WordPress, en un plugin dependiente, o en un hook mal ejecutado, tu editor lo interceptará y te mostrará en qué parte exacta ocurrió, permitiéndote rastrear el origen sin depender de mensajes de error visibles.

Conclusión

Aunque Studio todavía no ofrece una integración nativa con XDebug, gracias a wp-env puedes depurar tu plugin en tiempo real y con total visibilidad.

Esto mejora enormemente la experiencia de desarrollo y te permite detectar errores complejos mucho más rápido que con var_dump() o error_log().