Xdebug, herramienta avanzada para la depuración de código PHP

En el desarrollo de aplicaciones PHP es habitual, incluso en los programadores seniors, realizar depuración de errores basándose en prueba y error, por medio de funciones como var_dump, print_r, echo o helpers como dd en frameworks como Laravel, y aunque es cierto que en la mayoría de los casos puede ser suficiente, en otros, se requerirá de una solución de depuración más avanzada.

Xdebug es una extensión de PHP que permite precisamente esto, se integra con la mayoría de editores de código, pudiendo crear desde el mismo un flujo de depuración integrado por medio de puntos de interrupción (breakpoints), tracing en el uso de funciones o crear perfiles de rendimiento para buscar "cuellos de botella".

Xdebug suele utilizarse en los entornos en desarrollo, sea equipo local o similar, y aunque no común, puede haber casos específicos en los que se requiera hacer una depuración en remoto, desde el propio sistema en el que la web o app se encuentra en producción.

Este sería el caso que trataremos, a continuación, la conexión y depuración desde un IDE remoto como PHPStorm, NetBeans.

Habilitar la extensión Xdebug en PHP

Instalar Xdebug es tan sencillo como dirigirte al panel de control cPanel, sección Seleccionar versión de PHP, encontrarás en la zona inferior un listado de todas las extensiones disponibles, localiza y activa xdebug y listo.

Recomendamos que la actives y desactives cuando ya no la necesites, PHP rendirá mejor cuanto un número inferior de extensiones tenga activas, y aunque no es realmente significativo en el rendimiento, todo suma a la hora de ganar velocidad de carga.

Además, deberemos hacer unos ajustes en el fichero .htaccess de nuestro proyecto.

Si se está usando Xdebug 2.x (versión PHP < 7.2):

php_value xdebug.remote_enable 1
php_value xdebug.remote_host 127.0.0.1
php_value xdebug.remote_port 9000
php_value xdebug.idekey xdebug

Si, en cambio, se utiliza Xdebug 3.x (versión PHP >= 7.2):

php_value xdebug.client_host localhost
php_value xdebug.client_port 9003 
php_value xdebug.idekey xdebug

En versiones de PHP iguales o superiores a 7.2, la versión de Xdebug en uso es 3.x, sus diferentes modos no se pueden modificar en el .htaccess, requieren ser definidos en el fichero php.ini, para este acción, accedemos desde cPanel a Seleccionar versión de PHP, pestaña Options y en la zona inferior encontraremos un selector para modificar el valor de xdebug.mode.

Creando un túnel SSH para conectar con el servidor remoto

Los IDE conectan con un muerto determinado en la máquina para establecer una comunicación con Xdebug, en entornos locales la conexión es directa, pero en producción no se puede tener abierto un puerto para conexión remota por los riesgos de seguridad que ello implica, por ese motivo lo que se usa es un túnel.

Un túnel no es más que un enrutamiento o redireccionamiento, abre una conexión en el puerto que especifiques y enruta todos los datos hacia un puerto y servidor destino, para este fin utilizamos SSH.

Activa el acceso SSH

Importante como primer paso se compruebe que el acceso SSH está activado en el servicio de hosting al que vamos a conectar.

Creando un túnel SSH en Linux y Mac (OSX)

Abre la terminal del sistema operativo y ejecuta el siguiente comando.

Para Xdebug 2.x usamos el puerto 9000:

ssh -p93 -R 9000:localhost:9000 USUARIO_CPANEL@TU_DOMINIO.COM

Para Xdebug 3.x usamos el puerto 9003:

ssh -p93 -R 9003:localhost:9003 USUARIO_CPANEL@TU_DOMINIO.COM

No estamos más que conectando con el servidor vía SSH, y diciendo que cuando conectemos con el puerto 9000 o 9003 de nuestra máquina, se conecte realmente con ese mismo puerto en el servidor remoto.

Sustituye los datos en mayúscula por los de tu cuenta, a continuación se solicitará la contraseña de cPanel (a no ser que tengas configurado el acceso vía clave).

Una vez esté la sesión abierta, la dejamos en segundo plano para que el túnel se mantenga funcionando.

Creando un túnel SSH en Windows

Para conectar desde Windows usaremos Putty el cliente SSH de referencia para este sistema operativo, por lo que primero deberemos descargarlo e instalarlo desde su web oficial como si de cualquier otro programa se tratase.

Una vez abierto nos encontraremos una interfaz similar a la siguiente:

Completamos Host Name con el dominio al que vamos a conectar, Port indicamos 93, nuestro puerto de conexión SSH.

A continuación nos vamos al lateral y navegamos hasta Connection | SSH | Tunnels y configuramos tal como se muestra en la captura:

Source Port sería 9000 para Xdebug 2.x y 9003 para Xdebug 3.x, Destination establecemos localhost:9000 para Xdebug 2.x o localhost:9003 para Xdebug 3.x, marcamos Remote y Auto y click en Add para guardar el túnel.

Ya solo tenemos que hacer click en Open para abrir la sesión, a continuación se solicitará la contraseña de cPanel (a no ser que tengas configurado el acceso vía clave).

Configuración y uso de Xdebug para PHPStorm

PHPStorm no requiere prácticamente cambio alguno en su configuración, simplemente tenemos que tener el proyecto configurado para que sincronice, por ejemplo vía FTP y por supuesto el tunel SSH anteriormente creado debe estar abierto.

Tras esto hacemos click en el menú superior, sección Run, opción Start Listening for PHP Debug Connections para que esté preparado para las conexiones que vengan desde Xdebug.

Añadimos los breakpoints que queramos y accedemos a la dirección de nuestra web.

PHPStorm detectará que hay una conexión desde Xdebug, acepta y ya tendrás el control.

Configuración y uso de Xdebug para NetBeans

Damos por hecho que NetBeans ya está configurado para conectar o sincronizar los ficheros alojados en local con los que se tienen en remoto, por ejemplo usando FTP.

El siguiente paso es configurar Xdebug, accedemos a las preferencias de NetBeans, sección PHP, subsección Debugging y completamos.

Para Xdebug 2.x:

  • Debugger Port: 9000
  • Session ID: xdebug

Para Xdebug 3.x:

  • Debugger Port: 9003
  • Session ID: xdebug

Y nada más, guardamos, añadimos un breakpoint y ejecutamos el modo depuración, NetBeans ya podría controlar el flujo de depuración de nuestro código.

Otras alternativas

No son alternativas como tal, pero nos pueden facilitar la tarea de depuración sin tener que incurrir en la curva de configuración y aprendizaje de Xdebug, por un lado, sería utilizar PHP X-Ray para generar reportes de fácil comprensión en el caso de que lo que estemos haciendo es depurar problemas de rendimiento.

Por otro tenemos la aplicación ray de la empresa Spatie y aunque es de pago, merece la pena probarla, es un sencillo cliente para centralizar toda la información de depuración, pudiendo además depurar código remoto, ya que integra la conexión vía SSH.