XDEBUG: LA HERRAMIENTA ESENCIAL PARA DEPURAR Y OPTIMIZAR CÓDIGO PHP

Xdebug es la extensión php más poderosa y utilizada para desarrollo profesional. Transforma la experiencia de desarrollo al permitir depuración paso a paso, análisis de rendimiento, trazas detalladas y mucho más.

¿Qué es Xdebug?

Xdebug no es solo un depurador, ofreciendo varias funcionalidades clave:
  • Step Debugging: Depuración interactiva breakpoints, inspección de variables, stack traces.
  • Profiling: Genera información de rendimiento para identificar cuellos de botella.
  • Code Coverage: Ideal para pruebas unitarias (muestra qué líneas se ejecutan).
  • Function Tracing: Registra todas las llamadas a funciones con argumentos y valores de retorno.
  • Mejoras en var_dump y errores: Salidas mucho más legibles con colores, colapsables y stack traces mejorados.
  • Development Helpers — Muestra información útil en errores, excepciones y super globals.
En la versión 3, el rendimiento cuando está cargado pero inactivo es notablemente mejor que en la 2.x.

Instalación

La forma más sencilla es usar el Xdebug Wizard

Métodos comunes

  1. PECL:

    pecl install xdebug
  2. Windows: Descarga el fichero ".dll" correspondiente desde xdebug.org/download
  3. Docker: Añadir en el "Dockerfile" o "pecl install" en el contenedor.
Después de instalar Xdebug, agregar en el fichero "php.ini", o en un archivo "99-xdebug.ini":

zend_extension=xdebug

[xdebug]
xdebug.mode=debug,develop
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.idekey=VSCODE   ; o el que se use en el IDE
Nota importante: En Xdebug 3 ya no se usan las configuraciones antiguas tipo xdebug.remote_enable. Todo se centraliza en "xdebug.mode".

Configuración recomendada según el uso

Uso xdebug.mode recomendado Notas
Depuración diaria debug,develop Lo más común
Profiling profile Genera archivos .cachegrind
Pruebas (coverage) coverage Para PHPUnit
Solo trazas y var_dump mejorado develop,trace Bajo impacto
Todo (desarrollo local) debug,develop,trace,profile Solo en local

Ejemplos

Depuración paso a paso

  1. Poner un "breakpoint" (F9).
  2. Ejecutar el script o recargar la página.
  3. Usar F5, F10 (step over), F11 (step into), Shift+F11 (step out).

Profiling

//php.ini
xdebug.mode=profile
xdebug.output_dir="/tmp/profiles"
Abrir el archivo ".cachegrind" con herramientas como KCacheGrind en Linux o QCacheGrind.

Var_dump mejorado

Solo con "xdebug.mode=develop" ya se verán los var_dump mucho más útil y una interfaz gráfica mejorada.

Buenas prácticas y consejos

  • No activar nunca Xdebug en producción ya que tiene un impacto en el rendimiento.
  • Usar "xdebug.start_with_request=trigger" y una extensión de navegador como Xdebug Helper para Chrome/Firefox para activarlo solo cuando se necesite.
  • Configurar path mappings correctamente en Docker o entornos remotos.
  • Combinar con herramientas como Laravel Debugbar, Clockwork o Tracy para una experiencia aún más completa.
  • Actualízar regularmente

Alternativas y complementos

Aunque Xdebug sigue siendo el estándar, existen alternativas más ligeras para casos específicos:
  • PHP Debugger es un fork ligero solo para debugging.
  • Ray (de Spatie):para debugging visual.
  • PHP Debug Bar: barra de depuración en la propia aplicación.