Tutorial Instalar Depurador X-debug en Ubuntu
Xdebug es la herramienta de depuración (debugging) y análisis de rendimiento (profiling) más potente para PHP. Permite pausar la ejecución del código (breakpoints), inspeccionar variables en tiempo real y recorrer la pila de llamadas paso a paso directamente desde tu entorno de desarrollo (IDE) como VS Code o PhpStorm.
A continuación, te mostramos los pasos necesarios para instalarlo y configurarlo en un entorno Ubuntu.
Paso 1: Actualizar el sistema e identificar la versión de PHP
Antes de instalar nada, asegúrate de que tu sistema operativo y los paquetes de PHP están actualizados. Abre tu terminal y ejecuta:
sudo apt update && sudo apt upgrade
Identifica qué versión de PHP estás utilizando actualmente en tu sistema:
php -v
Paso 2: Instalar Xdebug
La forma más rápida y recomendada en Ubuntu es utilizar el gestor de paquetes oficial apt, ya que configurará automáticamente la extensión para la versión de PHP activa en tu sistema.
Ejecuta el siguiente comando (sustituye php por la versión específica si lo necesitas, por ejemplo php8.2-xdebug o php8.3-xdebug):
sudo apt install php-xdebug
Paso 3: Configurar Xdebug en el archivo php.ini
Una vez instalado, es necesario configurar Xdebug. En versiones recientes (Xdebug 3 y superiores), el comportamiento predeterminado ha cambiado para optimizar el rendimiento, por lo que debemos habilitar explícitamente el modo de depuración.
-
Localiza dónde se encuentra tu archivo de configuración de Xdebug o añade la configuración al final del archivo
php.inicorrespondiente a tu entorno (por ejemplo, en/etc/php/8.x/cli/php.iniy/etc/php/8.x/apache2/php.iniofpm). -
Abre el archivo de configuración con tu editor favorito:
sudo nano /etc/php/8.3/mods-available/xdebug.ini
(Nota: Ajusta la ruta según tu versión exacta de PHP).
-
Añade o verifica la siguiente configuración recomendada para Xdebug 3:
zend_extension=xdebug
[xdebug]
; Habilita el modo de depuración paso a paso
xdebug.mode=debug
; Inicia la depuración automáticamente al recibir una petición HTTP o CLI
xdebug.start_with_request=yes
; Puerto estándar para Xdebug 3 (en Xdebug 2 era el 9000)
xdebug.client_port=9003
; IP local del entorno de desarrollo
xdebug.client_host=127.0.0.1
; IDE Key para identificar la sesión (útil para extensiones de navegador)
xdebug.idekey=VSCODE
Guarda y cierra el archivo (Ctrl + O, Enter, Ctrl + X si usas Nano).
Paso 4: Reiniciar el servidor web o PHP-FPM
Para que los cambios surtan efecto, debes reiniciar el servicio encargado de procesar PHP.
-
Si utilizas Apache:
Bashsudo systemctl restart apache2 -
Si utilizas Nginx con PHP-FPM (reemplaza
8.3por tu versión de PHP):Bashsudo systemctl restart php8.3-fpm
Paso 5: Verificar la instalación
Para comprobar que Xdebug se ha instalado y cargado correctamente, ejecuta el siguiente comando en la terminal:
php -v
Deberías ver una salida similar a esta, indicando que la extensión está activa:
PHP 8.3.x (cli) (built: ...)
with Xdebug v3.3.x, Copyright (c) 2002-2024, by Derick Rethans
También puedes crear un archivo temporal info.php con el contenido <?php phpinfo(); ?> en la raíz de tu servidor local y buscar la sección de Xdebug en el navegador para confirmar que la tabla de configuración muestra el modo debug activo.
Siguiente paso recomendado
Con Xdebug ya operativo en tu servidor Ubuntu, el siguiente paso consiste en configurar tu IDE (como Visual Studio Code instalando la extensión PHP Debug, o PhpStorm) para que escuche en el puerto 9003 y comience a interceptar los puntos de interrupción (breakpoints) de tus proyectos PHP.