Ir al contenido principal

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=localhost: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=localhost:9229, puedes acceder a DevTools conectado con tu aplicación, con la posibilidad de inspeccionar todos los archivos de una instancia WordPress.

Chrome Devtools integrated with Xdebug

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.

Chrome Devtools integrated with Xdebug

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.

Xdebug en ejecución en VSCode

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.