Xdebug: depurar código PHP en remoto con PhpStorm o NetBeans

Depurar con var_dump, print_r o dd() funciona en la mayoría de los casos, pero hay errores que solo se entienden siguiendo el código paso a paso. Para eso está Xdebug: una extensión de PHP que se conecta con tu editor (PhpStorm, NetBeans, VS Code…) y te permite poner puntos de interrupción, avanzar línea a línea y ver el valor de cada variable.

Lo normal es usarlo en local, pero a veces el fallo solo ocurre en el servidor. En esta guía conectamos tu IDE con la web alojada en el hosting mediante un túnel SSH, sin abrir ningún puerto a Internet.

Xdebug ralentiza PHP mientras está activo y el IDE verá los datos que procese la petición (contraseñas, datos de clientes). Actívalo solo mientras depuras y desactívalo al terminar.

1. Activar Xdebug en cPanel

1. En cPanel, entra en Seleccionar versión de PHP.
2. En la pestaña Extensions, marca xdebug.
3. En la pestaña Options, busca xdebug.mode y pon debug. Este valor solo se puede cambiar aquí: en .htaccess no tiene efecto.

Con PHP 7.2 o superior la extensión es Xdebug 3, que usa el puerto 9003. Con PHP 7.1 o anterior es Xdebug 2, que usa el 9000; en ese caso cambia 9003 por 9000 en todos los pasos.

Después añade al principio del .htaccess de la web:

php_value xdebug.start_with_request trigger
php_value xdebug.client_host 127.0.0.1
php_value xdebug.client_port 9003
php_value xdebug.trigger_value MI_CLAVE_DEBUG

Cambia MI_CLAVE_DEBUG por una palabra que solo conozcas tú. Con start_with_request trigger Xdebug solo se activa en las peticiones que lleven esa clave, no en las visitas normales.

2. Abrir el túnel SSH

Xdebug es quien llama al IDE, no al revés: desde el servidor intenta conectar con 127.0.0.1:9003. El túnel SSH recoge esa conexión en el servidor y la lleva al puerto 9003 de tu ordenador, donde escucha el IDE.

Antes necesitas el acceso SSH activado en tu hosting. Si quieres entrar sin contraseña, configura una clave SSH.

Linux y macOS

Abre la terminal y ejecuta:

ssh -N -p 93 -o ExitOnForwardFailure=yes -R 127.0.0.1:9003:127.0.0.1:9003 USUARIO_CPANEL@TU_DOMINIO.COM

Sustituye USUARIO_CPANEL y TU_DOMINIO.COM por los tuyos. Te pedirá la contraseña de cPanel si no usas clave. Deja la terminal abierta mientras depuras: si la cierras, se cierra el túnel. Si el comando termina con un error de reenvío, el puerto 9003 ya está ocupado en el servidor; usa otro (por ejemplo 9010) en el túnel y en xdebug.client_port.

Windows con PuTTY

Descarga e instala PuTTY. Al abrirlo, en Host Name escribe tu dominio y en Port pon 93:

En el menú lateral ve a Connection > SSH > Tunnels y rellena:

• Source port: 9003
• Destination: 127.0.0.1:9003
• Marca Remote y Auto, y pulsa Add.

Deja sin marcar Remote ports do the same. Pulsa Open, escribe tu usuario y la contraseña de cPanel, y deja la ventana abierta mientras depuras.

3. Configurar el IDE

El IDE necesita los mismos ficheros que hay en el servidor y saber a qué ruta del servidor corresponde cada uno (el mapeo de rutas). Lo más cómodo es tener el proyecto sincronizado por FTP o SFTP con el hosting.

PhpStorm

1. Configura el proyecto con el servidor remoto (despliegue por FTP/SFTP). En Settings > PHP > Servers indica el dominio y el mapeo entre tu carpeta local y la del servidor (por ejemplo /home/USUARIO_CPANEL/public_html).
2. En Settings > PHP > Debug comprueba que el puerto de Xdebug es 9003.
3. Pulsa Run > Start Listening for PHP Debug Connections.
4. Pon un punto de interrupción y carga la web con la clave (ver paso 4).

PhpStorm mostrará un aviso de conexión entrante; acéptalo y tendrás el control:

NetBeans

Con el proyecto ya conectado al servidor (por ejemplo por FTP), ve a Preferencias > PHP > Debugging y rellena:

• Debugger Port: 9003
• Session ID: el mismo valor que pusiste en xdebug.trigger_value

Guarda, añade un punto de interrupción y lanza Debug Project. NetBeans abrirá el navegador con la clave y tomará el control:

4. Lanzar la depuración

Abre la página que quieres depurar añadiendo la clave a la URL:

https://tudominio.com/pagina?XDEBUG_SESSION=MI_CLAVE_DEBUG

Xdebug guarda una cookie y las siguientes peticiones de esa sesión también se depuran. También puedes usar la extensión de navegador Xdebug Helper (Chrome o Firefox) con la clave como IDE key: activas y desactivas la depuración con un clic.

Si el IDE no recibe la conexión:

• Comprueba que el túnel sigue abierto y que el IDE está escuchando.
• Comprueba con un phpinfo() que aparece la sección xdebug, que xdebug.mode es debug y que xdebug.client_port coincide con el del túnel.
• Si el IDE se para pero no en tu punto de interrupción, revisa el mapeo de rutas.

5. Al terminar

1. Cierra el túnel (la terminal o la ventana de PuTTY).
2. Quita las líneas xdebug.* del .htaccess.
3. En Seleccionar versión de PHP, desmarca xdebug.

Alternativas más sencillas

Si lo que buscas es por qué la web va lenta, no necesitas Xdebug: PHP X-Ray te dice qué funciones, consultas y llamadas externas consumen el tiempo, sin configurar nada en tu equipo.

Otra opción es Ray, de Spatie (de pago): sustituye a dump() mostrando la información en una aplicación de escritorio, y puede recibir datos de un servidor remoto por SSH.