Cómo configurar la depuración de PHP con Xdebug y VSCode

Debes prestar atención a algunas cosas cuando desarrolles aplicaciones web para obtener un producto final sin problemas. Los buenos desarrolladores siguen las mejores prácticas de desarrollo, incluyendo pruebas, depuración, etc., mientras crean aplicaciones robustas.

Este artículo trata los conceptos de depuración de PHP y las técnicas de codificación. Sigue leyendo para aprender más sobre la depuración de PHP.

Puedes empezar a depurar sin ninguna configuración. Pero, esto sólo se sugiere cuando necesites conectarte a un Servidor Web existente con Xdebug configurado o quieras ejecutar y depurar un script PHP rápidamente.

Empecemos por el nivel básico, en el que sueles escribir código PHP utilizando los comandos print_r(), var_dump() para depurar la salida del código escrito. Disponemos de muchas herramientas de depuración PHP, que permiten instar al usuario a corregir los errores durante la codificación, y algunas funciones que te muestran la salida correcta o errores/advertencias en caso de fallo del código. Aunque esta técnica de depuración de PHP es básica, se sigue utilizando.

¿Qué son los registros de errores de PHP?

Los registros de errores de PHP son instrumentos muy útiles para que los desarrolladores identifiquen y solucionen los problemas de sus aplicaciones. Los registros de errores de PHP muestran toda la información relativa a errores, avisos y advertencias en tiempo de ejecución del script, por ejemplo, el tipo de error, en qué archivo ha aparecido el error y el número de línea real donde se ha producido el error. Estos registros permiten a los desarrolladores identificar fallos en tiempo real y aplicar medidas correctoras estudiándolos.

¿Por qué son importantes los registros de errores de PHP?

• Depuración: Los registros de errores te ayudan a determinar errores de sintaxis, errores de ejecución y errores lógicos en tu código.
• Supervisión del rendimiento: Pueden identificar cuellos de botella de rendimiento o puntos de código ineficiente.
• La seguridad: Los registros pueden informarte sobre posibles vulnerabilidades o intentos de acceso por medios no autorizados.
• Seguridad en producción: En producción, los registros de errores te ayudan a rastrear los problemas sin revelar información sensible a los usuarios.

Configuración del registro de errores PHP

Para activar y configurar el registro de errores de PHP, debes cambiar la configuración de tu archivo php.ini o utilizar directivas en tiempo de ejecución como ini_set().

I. Directivas principales de php.ini:

Estas son las principales directivas para el registro de errores:

• log_errors: Activa o desactiva el registro de errores.

log_errors = On

• registro_errores: Aquí es donde se registrarán los errores. Utiliza una ruta absoluta para que sea obvio.

error_log = /var/log/php_errors.log

• error_reporting: Especifican qué tipo de errores deben registrarse. Por ejemplo

error_reporting = E_ALL

• E_ALL: Registra todos los errores, advertencias y avisos.
• E_ERROR | E_WARNING: Registra errores fatales y advertencias.

II. Registro por.htaccess (Por directorio):

Si php.ini no es accesible o modificable debido a problemas de acceso limitado, puedes registrar por directorio a través de.htaccess. Puedes añadir el siguiente bloque de código en el archivo .htaccess de tu aplicación en cuestión:

php_flag log_errors On
php_value error_log /path/to/php_errors.log

III. Configuración en tiempo de ejecución mediante ini_set():

También puedes activar el registro dinámicamente dentro de tus scripts PHP añadiendo el siguiente bloque de código:

ini_set('log_errors', 'On');
ini_set('error_log', '/path/to/php_errors.log');

Visualización de los registros de errores de PHP

Los registros de errores PHP se guardan de forma diferente según la configuración del alojamiento:

1. Ubicaciones por defecto:

• Para servidores Linux: /var/log/php_errors.log o /var/log/syslog
• Para servidores Windows: Visor de sucesos (en caso de que error_log esté configurado como syslog)

b. Instrucciones específicas para Cloudways:

En el caso de los servidores gestionados por Cloudways, puedes seguir fácilmente los pasos para ver tus logs sin realizar ningún esfuerzo adicional.

• Accede a tu panel de control de Cloudways.
• Ve a Gestión del Servidor > Monitorización > Registros.
• Ve a la sección «Registros de la aplicación» o «Registros del servidor» para comprobar los errores de PHP.

Lectura del registro de errores PHP

Los registros de errores de PHP te proporcionan una entrada informativa que describe lo ocurrido. Aquí tienes un ejemplo de entrada de registro:

[13-Mar-2025 12:00:00 UTC] PHP Fatal error: Uncaught Exception: Database connection failed in /var/www/html/index.php on line 25

Desglose del registro:

• Marca de tiempo: [13-Mar-2025 12:00:00 UTC]
• Tipo de error: PHP Error fatal
• Mensaje: Excepción no detectada: Falló la conexión a la base de datos
• Archivo y número de línea: /var/www/html/index.php en la línea 25

Con estas entradas de registro, puedes rastrear los errores hasta su origen y corregirlos adecuadamente.

Buenas prácticas del registro de errores de PHP

Tendrás que diferenciar los ajustes de Desarrollo y Producción de la siguiente manera.

En la configuración de desarrollo, puedes incluir lo siguiente:

display_errors = On
log_errors = On
error_reporting = E_ALL

En la configuración de producción, puedes incluir lo siguiente:

display_errors = Off
log_errors = On
error_reporting = E_ALL & ~E_NOTICE & ~E_DEPRECATED & ~E_STRICT

• Rota los Archivos de Registro: Evita que los archivos de registro se hagan demasiado grandes utilizando herramientas de rotación de registros como logrotate.
• Protege los archivos de registro: Limita el acceso a los archivos de registro mediante permisos de archivo (por ejemplo, chmod 600 /ruta/para/php_errores.log) para que no sea posible un acceso no autorizado.
• Supervisa los registros regularmente: Utiliza programas de supervisión como Rollbar o Loggly para analizar los registros en tiempo real.
• Registro específico del framework (por ejemplo, Laravel): Si trabajas con un framework como Laravel o Symfony, utiliza su registro incorporado para una mayor integración y flexibilidad.

¿Qué es el desarrollo PHP basado en depuración?

Antes no estaba seguro del término desarrollo basado en la depuración (DDD), pero un amigo depurador me dio esta idea. Su código contenía múltiples puntos de ruptura, y él iba respondiendo a cada línea hasta que obtenía la salida deseada.
No te confundas con los puntos de ruptura, ya que te los demostraré. DDD tiene un flujo similar a TDD, en el que primero defines todas las técnicas de depuración de PHP para la configuración y luego escribes el código para depurar si surge algún error.
Una vez que tengas una idea de DDD, deberías aprender sobre Xdebug, que te ayuda a entender el concepto de desarrollo PHP basado en la depuración. Ejecutar PHP con Xdebug te proporciona una visión completa de los errores, las respuestas y la cobertura del código.

¿Qué es Xdebug?

Imagina que has escrito tu código, y el código se rompe justo cuando lo compilas. Y lo peor es que no puedes identificar qué ha fallado. Xdebug es tu salvador en este caso.

Xdebug es una extensión de PHP que ayuda a los desarrolladores a depurar y suavizar el desarrollo de sus proyectos para detectar errores y resolverlos. Actualiza la función var_dump() de PHP y añade trazas de pila para avisos, advertencias, errores y excepciones.

Xdebug utiliza el protocolo de depuración DBGp y ofrece funciones de depuración y perfilado. Nos permite añadir puntos de interrupción y detener la ejecución del código en cada punto de interrupción para ver la salida de las variables en una sola iteración del código.

Así que Xdebug te permite ahorrar tu tiempo, que de otro modo se pierde en la depuración del código. Sin Xdebug, debes actualizar la página para volver a ver la salida. También puedes establecer puntos de interrupción independientes de los métodos para ver cuál está causando problemas.

Además, puedes añadir tantos puntos de interrupción como quieras en el código y utilizar un depurador PHP para comprobar cada código línea por línea.

Instalar Xdebug en PHP

Ahora es el momento de instalar Xdebug en PHP. Hay algunas opciones a través de las cuales puedes instalar Xdebug.

Ventanas:

Para los usuarios de Windows, Xdebug proporciona una herramienta asistente a través de la cual puedes descargar el archivo .dll relacionado. Para ello, primero, crea un archivo PHP en la carpeta, y añade la siguiente línea de código:

<?php

phpinfo();

?>

Ejecuta el archivo en el navegador. Verás la información PHP. Copia los datos y ponlos en la herramienta del asistente y pulsa el botón Analizar mi salida phpinfo() .

Esto te dará el siguiente resultado:

Ahora, descarga los archivos .dll y sigue las instrucciones mencionadas para colocar los archivos en el directorio xampp/php/ext. A continuación, sigue el paso 3 para activar Xdebug en el archivo php.ini y, por último, reinicia el servidor web.

MAC

Puedes instalar PHP7 Xdebug utilizando la extensión pecl:

pecl install xdebug

Linux

En distribuciones Linux como Debian, puedes utilizar Sudo para instalar Xdebug en PHP:

sudo apt install php-xdebug;

Ahora, abre el archivo etc/php/7.0/mods-available/xdebug.ini y añade el siguiente código para activar Xdebug:

xdebug.profiler_enable_trigger = 1

xdebug.profiler_enable = 0

xdebug.remote_enable = 1

xdebug.profiler_output_dir = "/tmp"

Ahora, reinicia el servidor Apache2.

sudo service apache2 restart;

GIT

También puedes clonarlo desde GitHub.

git clone git://github.com/xdebug/xdebug.git

Tras instalar Xdebug, abre el archivo php.ini y activa la extensión.

zend_extension="xdebug.so"

Ahora, comprueba la versión de PHP utilizando el comando `php -v`. Verás la versión de Xdebug instalada con PHP.

$ php -v

PHP 7.2.0RC6 (cli) (built: Nov 23 2017 10:30:56) ( NTS DEBUG )

Copyright (c) 1997-2017 The PHP Group

Zend Engine v3.2.0-dev, Copyright (c) 1998-2017 Zend Technologies

 with Xdebug v2.6.0-dev, Copyright (c) 2002-2017, by Derick Rethans

Configurar Xdebug en VSCode

Si quieres un flujo de trabajo fluido con Xdebug, puedes integrarlo en tu IDE favorito, como phpstorm, Zend studio y VScode. Vamos a configurar Xdebug en Visual Studio Code para depurar PHP.

Existe una popular extensión PHP de VSCode llamada php debug. Puedes encontrarla en la ventana de extensiones e instalarla.

Tras la instalación, debes volver a cargar la ventana VSCode. Ahora, ejecuta de nuevo el método phpinfo(); en cualquier archivo PHP para comprobar si Xdebug está activado o no.

Ahora haz clic en la pestaña consola de depuración y haz clic en añadir configuración.

Ahora, debes seleccionar el entorno que es PHP. VSCode añadirá ahora un archivo launch.json en el directorio raíz.

Por último, añade la propiedad runtimeExecutable a la lista después de port:

"runtimeExecutable": "C:\\xampp\\php\\php.exe"

Guarda el archivo launch.json. Abre la pestaña del modo de depuración y pulsa el botón verde de depuración para iniciar la opción de depuración.

Ahora verás unos cuantos elementos en la ventana, a través de los cuales puedes seleccionar cómo se mostrarán los registros en Xdebugger:

• Avisos
• Advertencias
• Errores
• Excepciones
• Todo

Navega hasta la sección Consola de depuración, que te muestra los detalles de los errores y los botones de ejecución de depuración en la parte superior.

En este punto, puedes añadir puntos de interrupción en las líneas de código que necesites depurar. Ten en cuenta que Xdebug añadirá el nombre del script de depuración PHP con el número de línea en la sección inferior izquierda:

Puedes ejecutar la aplicación en el navegador, y luego leer el código línea por línea, para ver los errores y depurarlos adecuadamente. Además, debes recordar algunas teclas de acceso directo a funciones para moverte por funciones y líneas de código:

F5: Continuar depurando

F10: Pasar por encima

F11: Entra en

Mayús + F11: Salir

Perfiles Xdebug

Xdebug también proporciona perfilado de código al igual que otras herramientas de perfilado, Blackfire y Tideways. Si quieres utilizar la opción de perfilado, debes activarla en el archivo php.ini.

xdebug.profiler_enable=1

xdebug.profiler_output_dir="C:\xampp\tmp"

Ahora, abre un archivo y empieza a introducir todos los registros de perfiles.

Palabras finales

La depuración es un aspecto importante de la programación; sin ella, no puedes saber qué ha fallado en tu código.

Este artículo ha demostrado cómo habilitar PHP para depurar con Xdebug y configurarlo en VSCode. También puedes integrarlo en Eclipse, PHPstorm y otros IDEs.

Para quienes se aventuran en el ámbito de la codificación extensiva, es primordial configurar un entorno de depuración robusto. Especialmente cuando se abordan aplicaciones intrincadas que abarcan miles de líneas, disponer de un depurador PHP resulta esencial para desenterrar errores y señales de advertencia. Con la ayuda de herramientas avanzadas y la fiabilidad del alojamiento web PHP, estarás equipado para navegar por las complejidades de la codificación y garantizar una experiencia de desarrollo perfecta.

Si hay algo sobre lo que quieras saber más, publica tus dudas y sugerencias en la sección de comentarios de abajo.

display_errors = On
error_reporting = E_ALL

log_errors = On
error_log = /path/to/logfile.log

error_reporting(E_ALL);
ini_set('display_errors', 1);

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

"php.executablePath": "C:/xampp/php/php.exe"

Salwa Mujtaba

Salwa Mujtaba es redactora de contenidos técnicos en Cloudways. Con una sólida formación en Informática y experiencia previa como jefa de equipo en Operaciones de Cloudways, aporta a sus escritos un profundo conocimiento de la Plataforma Cloudways. Salwa crea contenidos que simplifican conceptos complejos, haciéndolos accesibles y atractivos para los lectores. Cuando no está escribiendo, puedes encontrarla disfrutando de la buena música, leyendo un libro o pasando tiempo con su familia.

Get Connected on: Twitter Community Forum