Xdebug para depurar código PHP remoto

Xdebug permite recorrer código PHP con puntos de interrupción y examinar las variables de una petición desde un IDE compatible.

Utilízalo preferiblemente en local o en staging. Una sesión paso a paso puede exponer al IDE valores de variables, credenciales, tokens y datos personales procesados por la petición. Si excepcionalmente debes usarlo en producción, limita la prueba a una petición autorizada, utiliza un disparador privado y desactiva inmediatamente la extensión al terminar.

Xdebug puede introducir una sobrecarga apreciable según el modo activado y desactiva el JIT de PHP mientras está cargado. Comprueba su versión real; no la deduzcas únicamente a partir de la versión de PHP.

Comprobar la disponibilidad y activar Xdebug 3

Accede a cPanel > Seleccionar versión de PHP para la versión que ejecuta la ruta. Esta guía solo es aplicable si el selector ofrece la extensión xdebug y, en Options, la opción xdebug.mode. Activa la extensión y establece xdebug.mode como debug. Esta opción se aplica al arrancar PHP y no puede definirse desde .htaccess ni .user.ini.

Si alguna de estas opciones no aparece, no supongas que Xdebug está disponible para esa versión. No intentes instalar ni cargar otra extensión dentro de la cuenta.

Si el controlador PHP del dominio admite directivas Xdebug en .htaccess, añade temporalmente:

php_value xdebug.start_with_request trigger
php_flag xdebug.start_upon_error Off
php_flag xdebug.discover_client_host Off
php_value xdebug.client_host 127.0.0.1
php_value xdebug.client_port 9003
php_value xdebug.trigger_value VALOR_ALEATORIO_LARGO

Sustituye VALOR_ALEATORIO_LARGO por un valor privado. Estas opciones fijan el inicio por disparador, desactivan el inicio automático por errores y evitan descubrir el destino desde cabeceras. Comprueba sus valores efectivos: un código que llame a xdebug_break() también puede iniciar una conexión. El disparador privado controla la prueba habitual, pero no es un mecanismo de autenticación del protocolo. Si las directivas provocan un error 500, retíralas y comprueba el registro: el código por sí solo no demuestra que el controlador las rechace.

Crear un túnel SSH inverso

Xdebug inicia la conexión hacia el IDE; el IDE no conecta contra Xdebug. En esta configuración Xdebug conecta con 127.0.0.1:9003 en el servidor y el túnel SSH reenvía esa conexión a 127.0.0.1:9003 en tu equipo, donde escucha el IDE.

Activa previamente el acceso SSH y configura una clave siguiendo la guía de acceso SSH.

En Linux o macOS ejecuta:

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

-R abre el puerto 9003 únicamente en la interfaz de loopback del servidor y lo reenvía al puerto 9003 de tu equipo. Mantén la sesión abierta solo durante la prueba. Si SSH no puede crear el reenvío, terminará con error; no expongas en su lugar el puerto del depurador a Internet.

En Windows, configura PuTTY con el dominio y el puerto 93, usando la clave SSH autorizada en cPanel. En Connection | SSH | Tunnels, crea un reenvío Remote desde 127.0.0.1:9003 al destino 127.0.0.1:9003. No actives opciones que permitan escuchar en otras interfaces del servidor. Si la sesión rechaza el reenvío remoto, esta vía no está disponible para la cuenta.

Configurar el IDE y reproducir la petición

Abre en el IDE la misma versión del código que está desplegada y configura el mapeo entre la ruta remota y el proyecto local. Configura el puerto Xdebug 9003, activa la escucha de conexiones y añade los puntos de interrupción.

En PhpStorm, utiliza Run > Start Listening for PHP Debug Connections. En NetBeans, configura el puerto 9003 y el mapeo de rutas remotas. No es obligatorio sincronizar el proyecto mediante FTP para recibir una sesión de depuración.

Activa el disparador con una extensión de navegador compatible configurada con el mismo valor privado, o añade XDEBUG_TRIGGER=VALOR_ALEATORIO_LARGO únicamente a la petición de prueba. Reproduce la operación necesaria una sola vez. Acceder a la URL sin el disparador no debe iniciar la sesión.

Al terminar, desactiva el disparador, cierra el túnel SSH, elimina las directivas temporales, cambia xdebug.mode a off o desactiva la extensión y comprueba que no queda ningún registro de Xdebug con datos de la sesión.

Si necesitas analizar rendimiento en lugar de recorrer el código, utiliza PHP X-Ray.

Límites del túnel y comprobación

Loopback evita escuchar en una interfaz pública, pero no garantiza aislamiento entre todos los usuarios de un servidor compartido. Confirma con el proveedor que el reenvío está permitido y aislado para tu entorno. Si el puerto está ocupado, acuerda otro puerto remoto y ajusta xdebug.client_port; no cambies los datos de otro usuario.

Comprueba primero que una petición sin disparador no inicia la sesión y después que la petición de prueba alcanza el punto de interrupción correcto. No publiques una URL con el disparador: puede quedar en historiales o registros. Elimina también la cookie de depuración al terminar. Consulta las opciones de depuración de Xdebug si la sesión se inicia de forma inesperada.