Depuración de código PHP: técnicas y herramientas para profesionales

Introducción: Por qué la depuración es un superpoder del desarrollador

¿Alguna vez te has sentado por la noche, mirando fijamente el monitor, sin poder entender por qué tu sitio PHP muestra la pantalla blanca de la muerte? O, peor aún, ¿números incorrectos en un informe? Felicidades, te has topado con la depuración. Muchos principiantes temen esta palabra, pensando que la depuración de código PHP es solo para gurús elegidos. En realidad, es simplemente una habilidad que se puede y se debe entrenar.

En este artículo no solo enumeraremos funciones. Analizaremos escenarios reales: desde el simple var_dump() hasta la configuración de Xdebug en un IDE. Aprenderás cómo convertir el proceso de búsqueda de errores en una rutina estructurada, y no en una adivinanza. ¡Allá vamos!

1. Clásico del género: var_dump y print_r

La forma más sencilla de depuración PHP es insertar var_dump($variable) en un lugar sospechoso. Pero hay un detalle: no todos lo hacen correctamente.

var_dump correcto

Muchos escriben así:

var_dump($user);

Y obtienen un batiburrillo en la pantalla. Es mejor formatear la salida:

echo '<pre>';\nvar_dump($user);\necho '</pre>';\ndie(); // detener la ejecución para que no interfiera el resto de la salida

Y para arrays y objetos es más cómodo print_r() con el flag true, para guardar el resultado en una cadena:

$data = print_r($users, true);\nfile_put_contents('debug.log', $data, FILE_APPEND);

Consejo: Nunca dejes var_dump en producción. Usa depuración condicional:

if (defined('DEBUG_MODE') && DEBUG_MODE) {\n    var_dump($variable);\n}

2. Registro (logging): tu mejor amigo en producción

Cuando el sitio ya está en el servidor, no puedes simplemente mostrar el error en pantalla. Aquí es donde el registro PHP viene al rescate. La función incorporada error_log() es la base.

Cómo configurar error_log

En el archivo php.ini indica:

error_reporting = E_ALL\ndisplay_errors = Off\nlog_errors = On\nerror_log = /var/log/php_errors.log

Ahora todos los errores, incluyendo advertencias, se escribirán en el archivo. Y en el código puedes hacer así:

if ($result === false) {\n    error_log("Error de consulta a la BD: " . $db->error, 3, '/var/log/myapp.log');\n    // 3 — significa escritura en archivo, no en syslog\n}

Enfoque moderno: Monolog

Para proyectos serios usa la librería Monolog. Puede escribir en archivos, en Slack, en base de datos e incluso en Telegram. Ejemplo de conexión:

use Monolog\\Logger;\nuse Monolog\\Handler\\StreamHandler;\n\n$log = new Logger('my_app');\n$log->pushHandler(new StreamHandler(__DIR__ . '/app.log', Logger::WARNING));\n$log->warning('Usuario intentó acceder sin permisos', ['user_id' => 123]);

3. Xdebug: el motor de depuración reactivo

Si aún no has instalado Xdebug, estás perdiendo el tiempo. No es solo una herramienta, es un jetpack para el desarrollador. Permite establecer puntos de interrupción (breakpoints), ver valores de variables en tiempo real e incluso perfilar el código.

Instalación y configuración

Instálalo a través del gestor de paquetes:

pecl install xdebug\n# o para Ubuntu:\nsudo apt install php-xdebug

Añade en php.ini:

zend_extension=xdebug.so\nxdebug.mode=debug\nxdebug.start_with_request=yes\nxdebug.client_host=127.0.0.1\nxdebug.client_port=9003

Ahora configura tu IDE. En PhpStorm se hace en dos clics: configura el intérprete PHP y haz clic en "Start Listening for PHP Debug Connections".

Cómo funciona en la práctica

Colocas un punto de interrupción (círculo rojo) en la línea de código sospechosa. Ejecutas el script en el navegador con el parámetro ?XDEBUG_SESSION_START=1.