Primeros Pasos con Xdebug

Esta guía te muestra cómo habilitar Xdebug en WordPress Playground y comenzar a depurar tu código.

PHP WASM CLI vs Playground CLI

Primero, Xdebug está presente en dos CLI diferentes:

• @php-wasm/cli: Ejecuta scripts PHP independientes. Úsalo cuando estés depurando código PHP sin necesidad de un entorno WordPress.
• @wp-playground/cli: Ejecuta una instalación completa de WordPress. Útil para depurar plugins de WordPress, temas o funcionalidades del núcleo.

Para esta guía, utilizaremos @wp-playground/cli. Si no estás familiarizado con la herramienta, recomendamos leer la guía de @wp-playground/cli, pero el mismo proceso también puede aplicarse a la depuración de aplicaciones PHP con @php-wasm/cli.

Inicio rápido con npx

La forma más rápida de comenzar es usar npx, que no requiere instalación:

npx @wp-playground/cli@latest server --xdebug

Esto inicia WordPress en http://127.0.0.1:9400 con Xdebug habilitado. Ahora conectas un depurador.

Iniciando con DevTools

Para depurar con Chrome DevTools, agrega la bandera --experimental-devtools:

npx @wp-playground/cli@latest server --xdebug --experimental-devtools

La terminal mostrará una URL para conectar Chrome DevTools:

Starting a PHP server...
Setting up WordPress latest
Resolved WordPress release URL: https://downloads.w.org/release/wordpress-6.8.3.zip
Fetching SQLite integration plugin...
Booting WordPress...
WordPress is running on http://127.0.0.1:9400 with 1 worker(s)
Starting XDebug Bridge...
Connect Chrome DevTools to CDP at:
devtools://devtools/bundled/inspector.html?ws=127.0.0.1:9229

Chrome connected! Initializing Xdebug receiver...
XDebug receiver running on port 9003
Running a PHP script with Xdebug enabled...

Al hacer clic en la URL proporcionada, por ejemplo, devtools://devtools/bundled/inspector.html?ws=127.0.0.1:9229, puedes acceder a DevTools conectado con tu aplicación, con la posibilidad de inspeccionar todos los archivos de una instancia WordPress.

Para un ejemplo más práctico, vamos a depurar un plugin que tiene el siguiente código:

<?php
/**
 * Plugin Name: Simple Admin Message
 * Description: Displays a simple message in the WordPress admin
 * Version: 1.0
 * Author: Playground Team
 */

// Prevent direct access
if (!defined('ABSPATH')) {
    exit;
}

// Display admin notice
function sam_display_admin_message() {
    $message = 'Hello! This is a simple admin message.';
    ?>
    <div class="notice notice-info is-dismissible">
        <p><?php _e($message, 'simple-admin-message'); ?></p>
    </div>
    <?php
}
add_action('admin_notices', 'sam_display_admin_message');

En la carpeta donde se encuentra el plugin, ejecutemos el comando en nuestro terminal:

npx @wp-playground/cli@latest server --xdebug --experimental-devtools --auto-mount

El Playground CLI (@wp-playground/cli) detectará automáticamente la carpeta del plugin y la montará. Abriendo el proyecto en tu navegador y DevTools, podrás agregar breakpoints en el código de tu plugin y probarlo línea por línea.

Iniciando con integración IDE

Similar al proceso con DevTools, vamos a utilizar el mismo código del plugin anterior para depurar con VSCode, agrega la bandera --experimental-unsafe-ide-integration=vscode. Esta bandera optimizará el proceso de configuración para VSCode. Si trabajas con PhpStorm, simplemente agrega la bandera --experimental-unsafe-ide-integration=phpstorm.

Para depurar en VSCode necesitarás los siguientes prerrequisitos:

1. Una extensión para agregar soporte de PHP profiling, por ejemplo, PHP Profiler
2. Una carpeta .vscode/. Si el archivo launch.json no existe, no te preocupes, @wp-playground/cli lo creará.
3. Habilita los puntos de interrupción (breakpoints) en tu IDE. Algunos IDEs vienen con esta característica desactivada, así que presta atención a este detalle.

Si todo está listo, ejecuta el comando:

npx @wp-playground/cli@latest server --xdebug --experimental-unsafe-ide-integration=vscode --auto-mount

Ahora, ve a tu código, agrega los breakpoints y buenas pruebas.

Solución de problemas en PhpStorm

Si PhpStorm se detiene en la primera línea de archivos sin asignación de rutas o de scripts fuera de tu proyecto, puedes desactivar estas opciones en Settings > PHP > Debug > Xdebug:

• Force break at first line when no path mapping specified.
• Force break at first line when a script is outside the project.

Si las solicitudes que no alcanzan ningún punto de interrupción generan notificaciones no deseadas, desactiva Notify if debug session was finished without being paused en Settings > PHP > Debug > Settings (denominado Advanced settings en la documentación actual de JetBrains). Cuando esta opción está desactivada y no se alcanza ningún punto de interrupción, PhpStorm ejecuta el script sin detenerse ni iniciar una sesión de depuración.

Estas opciones evitan pausas o notificaciones no deseadas. No corrigen las asignaciones de rutas ni configuran los puntos de interrupción: sigues necesitando asignaciones de rutas correctas y puntos de interrupción activados en el código que quieres depurar.

Para más detalles, consulta la referencia de configuración de depuración de JetBrains y los ejemplos para PhpStorm.

Esta característica está en modo experimental. Hasta que se complete, necesitaremos tu retroalimentación. Por favor, conéctate con nosotros en el canal Slack #playground y comparte tus pensamientos.