Cómo Xdebug Puede Ayudarte a Ser un Mejor Desarrollador de WordPress

Como puede atestiguar cualquier desarrollador, el código nunca está listo para la producción después del primer borrador. Una parte clave del proceso de desarrollo es la depuración: eliminar o cambiar todas las partes de tu código que no funcionan.

La extensión Xdebug para PHP es una forma popular de erradicar y destruir todos los errores de tu código.

Uno de los grandes aspectos de Xdebug es su flexibilidad. Independientemente de tu marco o entorno de desarrollo preferido, podrás encontrar una versión de Xdebug que se adapte a tu flujo de trabajo. A partir de ahí, no tardarás en hacerte con la herramienta.

Este tutorial analizará Xdebug en profundidad, incluyendo el proceso de instalación, la integración en tu configuración y el uso general.

En primer lugar, vamos a darte más contexto sobre lo que es Xdebug y lo que hace.

Presentación de Xdebug

Xdebug es una de las extensiones más populares para depurar tu código PHP. La instalarás desde el entorno que elijas, y actúa como un «depurador de pasos».

En resumen, esto te permite trabajar en tu código línea por línea, de modo que puedes recorrerlo y ver cómo actúa e interactúa el código dentro de tu programa, así como investigar su salida. A partir de ahí, puedes hacer los cambios que consideres oportunos.

Pero Xdebug puede hacer mucho más:

• Puedes analizar el rendimiento de tu código mediante un conjunto de métricas y visualizaciones.
• Cuando ejecutas pruebas unitarias de PHP, puedes ver qué suites de código ejecuta y ejecuta.
• Xdebug incluye capacidades de «rastreo», que escribirán cada llamada a una función en el disco. Esto incluirá argumentos, asignaciones de variables y valores de retorno.
• Xdebug también introduce mejoras en el informe de errores estándar de PHP. Más adelante hablaremos de esto.

Dado el conjunto de características, hay muchas formas de utilizar Xdebug (y cualquier depurador similar) dentro de tu flujo de trabajo. Las cubriremos en la siguiente sección.

Por Qué Querrías Usar Xdebug

Muchos desarrolladores no tienen un flujo de trabajo de depuración dedicado que utilice herramientas y extensiones de terceros. Esto se debe a que PHP incluye su propio registro de errores rudimentario. Utilizarás comandos como error_log, var_dump y print para ver los resultados de las variables y las llamadas a funciones.

Por ejemplo, hay muchos fragmentos que puedes reutilizar para el desarrollo de WordPress: Stack Overflow está repleto de ellos:

function log_me($message) {
  if ( WP_DEBUG === true ) {
      if ( is_array($message) || is_object($message) ) {
          error_log( print_r($message, true) );
      } else {
           error_log( $message );
      }
  }
}

Sin embargo, este enfoque tiene algunos inconvenientes importantes:

• Primero debes asegurarte de habilitar los registros de errores para la plataforma con la que estás trabajando. En este caso, querrás habilitar WP_DEBUG (más sobre esto en breve).
• Este ejemplo de depuración por «volcado» ofrece menos posibilidades de investigación que la depuración por pasos. Aquí, sólo puedes sacar lo que definas.

El último punto requiere mucho esfuerzo manual, especialmente si tu trabajo diario no es como administrador del sistema. Por ejemplo, si quieres depurar un bloque de código, puedes añadir tu fragmento en función de una variable que definas. Sin embargo, puede que no sea el origen del problema o que ni siquiera indique lo que está ocurriendo.

En su lugar, una herramienta como Xdebug puede hacer su magia para proporcionar un mayor alcance:

• Puedes «romper» tu código en varios puntos de la ejecución para ver lo que ocurre en tiempo real.
• Hay una miríada de métricas, visualizaciones, ramas y más para ayudarte a averiguar qué está haciendo tu código y cómo responde.
• A veces, incluso puedes cambiar los valores sobre la marcha durante el proceso de depuración. Esto ofrece un valor inmenso, incluso para conjuntos de código que funcionan bien. Básicamente, puedes realizar pruebas unitarias manuales en cualquier momento.
• Como utilizas los puntos de interrupción para marcar las áreas a depurar, no necesitas trabajar con fragmentos dentro de tu código. Esto mantiene tu código más limpio y reduce el número de problemas futuros.

En general, utilizar una herramienta como Xdebug es una decisión proactiva más que reactiva. Puedes utilizar la depuración por pasos como parte del proceso central de desarrollo, de forma similar a la implementación de pruebas unitarias como parte del desarrollo dirigido por pruebas (TDD).

Cómo Activar el Registro de Errores de PHP

Aunque podrías depurar tu código sin un error específico, a menudo es bueno saber si se produce un problema sin tener abierto Xdebug. Esto te da un punto de partida para la exploración. No es estrictamente necesario, pero puede ser una parte útil de tu cadena.

Para informar de cada error que surja, tendrás que añadir una línea al principio del archivo PHP correspondiente:

error_reporting(E_ALL);

Esta es una orden de captura, y puedes conseguir lo mismo utilizando la función ini_set función:

ini_set('error_reporting', E_ALL);

Esto te permite cambiar la configuración dentro de tu archivo php.ini proyecto por proyecto. Aunque podrías entrar en este archivo y hacer un cambio manual, a menudo es mejor trabajar con ini_set para cambiar el parámetro específico:

ini_set('display_errors', '1');

Una vez que tengas los informes de errores activos configurados a tu gusto, puedes empezar a trabajar con Xdebug.

Cómo utilizar Xdebug

En las próximas secciones, te mostraremos cómo utilizar Xdebug, incluyendo los pasos que necesitarás para configurar las cosas. Aunque no podemos cubrir todos los aspectos de la herramienta, esta guía de inicio rápido te hará avanzar rápidamente.

Sin embargo, primero tienes que instalar Xdebug. Veamos cómo hacerlo.

1. Instala Xdebug para tu sistema operativo (SO)

Dado que Xdebug se adapta a cualquier número de configuraciones, el proceso exacto para cada una de ellas será ligeramente diferente. A nivel de SO, hay algunas diferencias:

• Windows: Se trata de un proceso de configuración algo complicado que implica utilizar un archivo PHP existente y un asistente de instalación, para luego descargar la versión adecuada para tu sistema.
• Linux: El método aquí es posiblemente el más sencillo: Puedes utilizar un gestor de paquetes para instalar Xdebug, o la PHP Extension Community Library (PECL).
• Mac: Este método también es sencillo: Una vez instalado PECL, puedes ejecutar pecl install xdebug desde una instancia de Terminal. También necesitarás tener instaladas las herramientas de línea de comandos XCode y PHP en tu sistema.

Sin embargo, la mayoría de los usuarios no querrán quedarse con una instancia de Xdebug a nivel de sistema. En su lugar, querrán integrarlo en su propio entorno de staging.

2. Integrar Xdebug en tu entorno de staging

Una vez que hayas instalado Xdebug para tu sistema operativo, debes conectarlo a tu entorno.

Hay tantos sistemas y herramientas compatibles que no podemos entrar en todos ellos. Más adelante, te ofreceremos instrucciones tanto para DevKinsta como para PhpStorm. Aun así, hay muchos otros entornos populares entre los que elegir. A continuación te presentamos algunas de nuestras principales recomendaciones.

Varying Vagrant Vagrants (VVV)

VVV es uno de los entornos nombrados en el sitio web de Make WordPress:

La buena noticia es que VVV ya incluye una versión de Xdebug, pero tienes que activarla. Puedes hacerlo mediante Secure Shell (SSH) dentro de una ventana de Terminal:

vagrant ssh -c "switch_php_debugmod xdebug"

Sin embargo, hay un pequeño impacto en el rendimiento, y tendrás que volver a activar esta opción si aprovisionas tus sitios.

Laravel Valet

Para algunos usuarios, Valet de Laravel representa un entorno de staging web casi perfecto. Y lo que es mejor, puedes integrar Xdebug con él.

Para ello, tendrás que crear un archivo de configuración para el depurador. Puedes encontrar tu propia ruta utilizando php --ini en la línea de comandos, que te devolverá unas cuantas rutas de archivos diferentes:

A continuación, crea un nuevo archivo xdebug.ini en la ruta de los archivos .ini adicionales. En nuestro ejemplo, está en /opt/homebrew/etc/php/7.4/conf.d.

Una vez que abras este nuevo archivo, abre también la ruta del archivo de configuración cargado (tu archivo principal php.ini). Con ambos abiertos, añade lo siguiente al final:

• php.ini: zend_extension="xdebug.so"
• xdebug.ini: xdebug.mode=debug

Una vez que hayas guardado los cambios, ejecuta valet restart desde el Terminal, y añade phpinfo(); exit; a uno de los archivos de tu sitio. Querrás comprobar si esto funciona mediante una carga rápida de la página dentro del navegador.

Ten en cuenta que es posible que tengas que reiniciar PHP utilizando sudo brew services restart php, así como comprobar que la instalación de Xdebug en tu sistema es correcta utilizando php --info | grep xdebug. Notarás las líneas específicas de Xdebug dentro de la salida:

A partir de aquí, puedes buscar la forma de incorporar Xdebug a tu editor de código preferido.

XAMPP

Al igual que Valet, el proceso de XAMPP consta de varias partes. Sin embargo, las versiones de Windows y macOS tienen dos procesos diferentes.

Comienza instalando XAMPP, y luego realiza una rápida comprobación para ver si el archivo php_xdebug.dll (Windows) o xdebug.so (macOS) existe en tu sistema:

Si el archivo existe, puedes pasar a la configuración. Si no, primero tendrás que descargar el binario adecuado para Windows -un archivo de 64 bits para tu versión de PHP preferida- o instalar algunas dependencias más si estás en un Mac.

En el caso de Windows, cambia el nombre del archivo DLL php_xdebug.dll y muévelo a la ruta del archivo \xampp\php\ext. A continuación, abre el archivo \xampp\php\php.ini en tu editor de código preferido y añade lo siguiente

output_buffering = Off

En la sección [XDebug], añade las tres líneas siguientes:

zend_extension=xdebug
xdebug.mode=debug
xdebug.start_with_request=trigger

Una vez que guardes los cambios, reinicia Apache y prueba el Xdebug.

Para Mac, querrás asegurarte de que instalas las herramientas de línea de comandos de Xcode utilizando xcode-select --install en una instancia de Terminal. Después de eso, hay tres paquetes que querrás instalar usando Homebrew:

brew install autoconf automake libtool

En algunos casos, también tendrás que reinstalar XAMPP para obtener tanto el programa principal como los «Archivos de desarrollador». Deberías poder reinstalar sólo estos archivos, pero querrás realizar primero una copia de seguridad de tu configuración actual.

A continuación, navega hasta la descarga de la carpeta de fuentes de Xdebug en tu sistema y descomprime el archivo TGZ. Dentro de una ventana de Terminal, navega hasta ese directorio y ejecuta lo siguiente:

phpize
pecl install xdebug

Ten en cuenta que es posible que tengas que usar sudo aquí también. Desde aquí, puedes editar el archivo php.ini de XAMPP. En la mayoría de las instalaciones de macOS, lo encontrarás en /Applications/XAMPP/xamppfiles/etc/php.ini. Dentro de este directorio, también encontrarás la ruta de tu archivo xdebug.so — anótalo y utilízalo en lugar del marcador de ruta del archivo para este fragmento:

[xdebug]
zend_extension=/path/to/xdebug.so
xdebug.mode=develop,degug
xdebug.start_with_request=yes

Para probar si esto funciona, crea un nuevo archivo xdebug_info.php dentro del directorio principal de htdocs XAMPP. Dentro, añade lo siguiente:

<?php
xdebug_info();

…luego actualiza Apache y prueba Xdebug en el navegador.

Utilizar PhpStorm con Xdebug

Una vez que hayas instalado Xdebug a través del sistema operativo y de tu entorno de staging, también tendrás que ver el propio depurador. Lo harás a través del editor de código que hayas elegido o del entorno de desarrollo integrado (IDE). Al igual que con tu entorno, hay muchos para elegir, y cada uno puede tener un enfoque diferente.

Dicho esto, muchos desarrolladores optan por utilizar PhpStorm de JetBrains. De hecho, PhpStorm ofrece «asistencia para WordPress» y es una opción popular por muchas otras razones.

El sitio web de JetBrains incluye instrucciones completas para conectar Xdebug y PhpStorm, pero las repasaremos aquí.

En primer lugar, ve a la página Lenguajes y marcos > PHP dentro del panel de Preferencias. Aquí, abre el menú «Más elementos» junto al campo desplegable Intérprete CLI:

Esto mostrará algunos detalles más sobre tu versión de PHP y tu intérprete. Si haces clic en la elipsis de Más elementos junto a la opción Archivo de configuración, verás las rutas completas de tu archivo php.ini:

A continuación trabajarás con este archivo PHP para continuar con el proceso de configuración.

Trabajar con el archivo php.ini

La primera tarea aquí es editar cualquier línea que afecte al funcionamiento de Xdebug con PhpStorm.

Dentro del archivo php.ini, busca las siguientes líneas y elimínalas o coméntalas:

zend_extension=<path_to_zend_debugger>
zend_extension=<path_to_zend_optimizer>

Estas líneas no estarán presentes en todos los casos, así que no te alarmes si no las ves.

A continuación, añade lo siguiente al archivo:

[xdebug]
zend_extension="xdebug.so"
xdebug.mode=debug
xdebug.client_host=127.0.0.1
xdebug.client_port="<the port (9003 by default) to which Xdebug connects>"

Hay que tener en cuenta algunas cosas sobre este conjunto de código:

• Puede que ya tengas una sección [xdebug], en cuyo caso puedes omitir la primera designación.
• La entrada zend_extension puede necesitar que añadas la ruta completa de xdebug.so para conectarte.
• Aunque parezca un marcador de posición, el parámetro xdebug.client_port es la forma en que lo establecerás dentro de tu código.

Una vez que los añadas, guarda y cierra el archivo, y luego prueba la versión de PHP desde la línea de comandos (usando php --version):

Si tienes una versión de Xdebug que funciona, se mostrará como una de las extensiones de PHP. También puedes añadir phpinfo(); a un nuevo archivo y probarlo en el navegador.

Esto es casi todo lo que necesitas hacer para que Xdebug funcione como tu depurador por defecto con PhpStorm. El último paso antes de utilizarlo es instalar una extensión de ayuda al navegador.

Instalar una extensión de ayuda al navegador

La última conexión clave que tendrás que hacer es entre tu navegador y PhpStorm, que se consigue activando la depuración por pasos en el servidor. Aunque podrías hacerlo desde la línea de comandos utilizando valores especiales de GET o POST, es más sencillo utilizar una extensión.

Recomendamos utilizar la extensión dedicada Xdebug Helper. Puedes instalarla en el navegador que prefieras:

• Xdebug Helper para Chrome/Chromium/Brave
• Ayudante de Xdebug para Firefox

Si quieres explorar otras extensiones, el sitio web de JetBrains ofrece algunas opciones adicionales para los navegadores más populares.

Una vez que hayas instalado la extensión del navegador que hayas elegido, no deberías tener que ajustar ninguna otra opción de configuración. A partir de aquí, puedes empezar a utilizar Xdebug con PhpStorm.

Uso de Xdebug

Aunque aquí utilizaremos PhpStorm, verás un diseño y una interfaz similares entre los distintos IDE, aunque también habrá algunas diferencias obvias.

Hay algunos conceptos que se combinan para formar toda la experiencia de depuración:

• Puntos de interrupción: Son los puntos en los que Xdebug se detendrá para permitirte inspeccionar la salida. Puedes establecer tantos como quieras.
• Escuchar las conexiones: Puedes activar y desactivar esta opción, aunque la mayoría de los desarrolladores la dejarán siempre activada.
• La pantalla de depuración: La mayor parte de tu tiempo lo pasarás en la interfaz de depuración: es donde trabajarás con las distintas líneas de código, variables y parámetros.

El primer paso es activar la escucha: no podrás depurar nada sin ella. Para ello, haz clic en la opción Ejecutar > Iniciar la escucha de las conexiones de depuración de PHP en la barra de herramientas:

Como alternativa, puedes hacer clic en el icono del «teléfono» dentro de la barra de herramientas de PhpStorm:

Cualquiera de estas opciones iniciará la escucha de conexiones.

A partir de aquí, puedes empezar a establecer puntos de ruptura dentro de los canales del editor de código. Un punto rojo indica un punto de ruptura, en el que puedes hacer clic para activarlo:

Cuando quieras depurar tu código, lo más sencillo es empezar a escuchar, establecer puntos de interrupción y luego dirigirte a la página específica en tu navegador. Localiza el icono de tu extensión dentro del navegador, haz clic en él y selecciona la opción «Depurar»:

Esto abrirá el depurador en PhpStorm y dará las buenas o malas noticias:

Si haces clic con el botón derecho en los distintos valores, atributos, parámetros y variables, podrás acceder a otro menú contextual. Esto te da mucho margen para probar y depurar tu código:

Por ejemplo, podrías establecer diferentes valores para las variables a lo largo de la ruta. Esto podría ser un intento deliberado de romper tu código y ver qué ocurre, o podría ser una forma de probar un código que ya necesita una corrección. En cualquier caso, esto te proporciona un método fantástico para depurar tu código sin tener que alterarlo primero.

Cómo Te Ayuda Kinsta a Ddepurar Tu Sitio Web de WordPress

WordPress viene con su propio conjunto de opciones de depuración a través de WP_DEBUG y otras herramientas, como Query Monitor. Éstas habilitan un modo en el que empezarás a ver mensajes de error previamente ocultos en todo tu sitio y en el panel de control. A partir de ahí, puedes empezar a averiguar cuál es el problema.

También puedes guardar esos mensajes de error utilizando WP_DEBUG_LOG, lo que te proporciona una forma de documentar los problemas de tu sitio. Cubrimos cómo configurar esto en otro artículo del blog. Esto es muy fácil de configurar a través de tu panel de MyKinsta (y la pantalla Sitios > Herramientas):

Si combinas esto con la herramienta gratuita de entorno local DevKinsta, también tendrás una forma de activar y desactivar WP_DEBUG con un solo clic para cada sitio que crees:

Esto significa que puedes detectar errores en tu sitio durante el desarrollo, y asegurarte de que no lleguen a tu sitio en vivo. Estos modos también son fáciles de desactivar, lo que es vital para la seguridad del sitio y de los usuarios.

Todos los planes de Kinsta también vienen con la herramienta Kinsta APM integrada, que es nuestra herramienta de monitorización del rendimiento diseñada a medida para los sitios de WordPress.

Atajos de Comandos

Antes de terminar este post, debemos mencionar los atajos.

Como muchas otras piezas de software, hay varias formas de navegar por Xdebug (y PhpStorm) utilizando sólo el teclado. De hecho, puedes incluso utilizar la línea de comandos para depurar scripts PHP.

Una vez que Xdebug esté funcionando, puedes utilizar los siguientes comandos para desplazarte:

Aunque tu editor de código específico tendrá sus propios atajos dedicados, aquí nos centramos en PhpStorm. Echa un vistazo a esta tabla de atajos de teclado para usar Xdebug con PhpStorm:

Afortunadamente, no hay mucho que memorizar aquí. Debes abrir el depurador, establecer puntos de interrupción por línea, escuchar las conexiones y ejecutar tus scripts.

Sin embargo, si necesitas un atajo para una tarea concreta, puedes utilizar el comando Buscar Acción de PhpStorm:

Una vez que empieces a escribir en este espacio, se te mostrará una lista dinámica de comandos y atajos relacionados. También puedes encontrar una versión en PDF de todos los atajos de teclado a través del menú Ayuda > Atajos de teclado en PDF.

Si quieres ver los atajos en tiempo real mientras trabajas con el ratón, JetBrains proporciona el plugin Key Promoter X:

Esta práctica herramienta mostrará notificaciones de tu última acción realizada, junto con su atajo de teclado relacionado. Una vez que aprendas y utilices los atajos, podrás eliminar este plugin y recuperar ese valioso espacio en tu pantalla.

Resumen

La práctica de la depuración ha recorrido un largo camino desde sus humildes comienzos; ahora abarca un ámbito mucho más amplio de lo que sus progenitores podrían haber imaginado. Para llevar a cabo un trabajo minucioso a la hora de arreglar tu código PHP, necesitarás utilizar una herramienta competente. Hay muchas extensiones y herramientas magníficas entre las que elegir, pero Xdebug es una de las principales.

Como hemos visto, Xdebug puede adaptarse incluso a los gustos más eclécticos en cuanto a editores de código, y es especialmente bueno cuando se combina con PhpStorm. Sin embargo, independientemente de tu configuración, a menudo habrá una versión de Xdebug que se adapte a tus necesidades. En general, es una herramienta potente, flexible e intuitiva.

¿Crees que Xdebug merece sus grandes elogios, o hay otra herramienta de depuración que prefieres? Háznoslo saber en la sección de comentarios más abajo