Empezando con Tracy

La librería Tracy es una útil ayuda diaria para el programador PHP. Te ayudará a:

  • detectar y corregir errores rápidamente
  • registrar errores
  • imprimir variables
  • medir el tiempo de ejecución de scripts y consultas de base de datos
  • monitorizar los requisitos de memoria

PHP es un lenguaje perfecto para cometer errores difíciles de detectar, ya que da a los desarrolladores una considerable libertad. Por eso, la herramienta de depuración Tracy es aún más valiosa. Representa la cima absoluta entre las herramientas de diagnóstico para PHP.

Si hoy te encuentras con Tracy por primera vez, créeme, tu vida comenzará a dividirse en la de antes de Tracy y la de después. ¡Bienvenido a la mejor parte!

Instalación

La mejor manera de instalar Tracy es descargar el último paquete, o usar Composer:

composer require tracy/tracy

También puedes descargar el paquete completo como un archivo tracy.phar.

Uso

Activamos Tracy llamando al método Tracy\Debugger::enable() lo antes posible al principio del programa, antes de enviar cualquier salida:

use Tracy\Debugger;

require 'vendor/autoload.php'; // o tracy.phar

Debugger::enable();

Lo primero que notarás en la página es la Tracy Bar en la esquina inferior derecha. Si no la ves, puede significar que Tracy se está ejecutando en modo de producción. Tracy, por razones de seguridad, solo es visible en localhost. Para probar si funciona, puedes cambiarla temporalmente al modo de desarrollo usando el parámetro Debugger::enable(Debugger::Development).

Tracy Bar

La Tracy Bar es un panel flotante que aparece en la esquina inferior derecha de la página. Podemos moverla con el ratón y recordará su posición después de recargar la página.

Se pueden añadir otros paneles útiles a la Tracy Bar. Encontrarás muchos en los complementos, o incluso puedes escribir los tuyos propios.

Si no quieres mostrar la Tracy Bar, configura:

Debugger::$showBar = false;

Visualización de errores y excepciones

Seguro que sabes bien cómo PHP notifica los errores: imprime algo como esto en el código fuente de la página:

Parse error:  syntax error, unexpected '}' in HomePresenter.php on line 15

o en caso de una excepción no capturada:

Fatal error:  Uncaught Nette\MemberAccessException: Call to undefined method Nette\Application\UI\Form::addTest()? in /sandbox/vendor/nette/utils/src/Utils/ObjectMixin.php:100
Stack trace:
#0 /sandbox/vendor/nette/utils/src/Utils/Object.php(75): Nette\Utils\ObjectMixin::call(Object(Nette\Application\UI\Form), 'addTest', Array)
#1 /sandbox/app/Forms/SignFormFactory.php(32): Nette\Object->__call('addTest', Array)
#2 /sandbox/app/Presentation/Sign/SignPresenter.php(21): App\Forms\SignFormFactory->create()
#3 /sandbox/vendor/nette/component-model/src/ComponentModel/Container.php(181): App\Presentation\Sign\SignPresenter->createComponentSignInForm('signInForm')
#4 /sandbox/vendor/nette/component-model/src/ComponentModel/Container.php(139): Nette\ComponentModel\Container->createComponent('signInForm')
#5 /sandbox/temp/cache/latte/15206b353f351f6bfca2c36cc.php(17): Nette\ComponentModel\Co in /sandbox/vendor/nette/utils/src/Utils/ObjectMixin.php on line 100

Orientarse en tal salida no es precisamente fácil. Si activamos Tracy, el error o la excepción se mostrarán de una forma completamente diferente:

El mensaje de error literalmente grita. Vemos parte del código fuente con la línea resaltada donde ocurrió el error y la información Call to undefined method Nette\Http\User::isLogedIn() explica claramente de qué error se trata. Toda la página es además interactiva, podemos hacer clic para ver más detalles. Pruébalo.

¿Y sabes qué? De esta manera captura y muestra incluso errores fatales. Sin necesidad de instalar ninguna extensión.

Errores como un error tipográfico en el nombre de una variable o el intento de abrir un archivo inexistente generan mensajes de nivel E_NOTICE o E_WARNING. Estos pueden pasarse por alto fácilmente en los gráficos de la página, incluso pueden no ser visibles en absoluto (a menos que mires el código fuente de la página).

O pueden mostrarse igual que los errores:

Debugger::$strictMode = true; // mostrar todos los errores
Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // todos los errores excepto los avisos de deprecación

Nota: Tracy, después de la activación, cambia el nivel de reporte de errores a E_ALL. Si quieres cambiar este valor, hazlo después de llamar a enable().

Modo de desarrollo vs producción

Como puedes ver, Tracy es bastante locuaz, lo cual se puede apreciar en el entorno de desarrollo, mientras que en un servidor de producción causaría un completo desastre. Allí no se debe imprimir ninguna información de depuración. Tracy, por lo tanto, dispone de autodetección de entorno y si ejecutamos el ejemplo en un servidor en vivo, el error se registrará en lugar de mostrarse y el visitante solo verá un mensaje comprensible para el usuario:

El modo de producción suprime la visualización de toda la información de depuración que enviamos mediante dump(), y por supuesto también de todos los mensajes de error que genera PHP. Por lo tanto, si has olvidado algún dump($obj) en el código, no tienes que preocuparte, en el servidor de producción no se imprimirá nada.

¿Cómo funciona la autodetección de modo? El modo es de desarrollo si la aplicación se ejecuta en localhost (es decir, dirección IP 127.0.0.1 o ::1) y no hay presente un proxy (es decir, su cabecera HTTP). De lo contrario, se ejecuta en modo de producción.

Si queremos habilitar el modo de desarrollo también en otros casos, por ejemplo, para programadores que acceden desde una dirección IP específica, la indicamos como parámetro del método enable():

Debugger::enable('23.75.345.200'); // también se puede indicar un array de direcciones IP

Definitivamente recomendamos combinar la dirección IP con una cookie. En la cookie tracy-debug guardamos un token secreto, p.ej. secret1234, y de esta manera activamos el modo de desarrollo solo para programadores que acceden desde una dirección IP específica y que tienen el token mencionado en la cookie:

Debugger::enable('secret1234@23.75.345.200');

También podemos establecer directamente el modo de desarrollo/producción usando la constante Debugger::Development o Debugger::Production como parámetro del método enable().

Si usas Nette Framework, consulta cómo configurar el modo para él y ese se usará posteriormente también para Tracy.

Registro de errores

En modo de producción, Tracy registra automáticamente todos los errores y excepciones capturadas en un log de texto. Para que el registro pueda llevarse a cabo, debemos establecer la ruta absoluta al directorio de logs en la variable $logDirectory o pasarla como segundo parámetro del método enable():

Debugger::$logDirectory = __DIR__ . '/log';

El registro de errores es, al mismo tiempo, extremadamente útil. Imagina que todos los usuarios de tu aplicación son en realidad betatesters que realizan gratuitamente un trabajo excelente en la búsqueda de errores y cometerías una tontería si desecharas sus valiosos reportes sin prestar atención en la papelera.

Si necesitamos registrar nuestro propio mensaje o una excepción que hemos capturado, usamos para ello el método log():

Debugger::log('Ocurrió un error inesperado'); // mensaje de texto

try {
	operacionCritica();
} catch (Exception $e) {
	Debugger::log($e); // también se puede registrar la excepción
	// o
	Debugger::log($e, Debugger::ERROR); // también envía una notificación por correo electrónico
}

Si quieres que Tracy registre errores de PHP como E_NOTICE o E_WARNING con información detallada (informe HTML), establece Debugger::$logSeverity:

Debugger::$logSeverity = E_NOTICE | E_WARNING;

Para un verdadero profesional, el log de errores es una fuente clave de información y quiere ser informado inmediatamente sobre cada nuevo error. Tracy le ayuda en esto, ya que puede informar sobre un nuevo registro en el log por correo electrónico. Determinamos a dónde enviar los correos electrónicos con la variable $email:

Debugger::$email = 'admin@example.com';

Si usas todo el Nette Framework, puedes configurar esto y otros ajustes en el archivo de configuración.

Sin embargo, para que no inunde tu buzón de correo electrónico, siempre envía solo un mensaje y crea el archivo email-sent. El desarrollador, después de recibir la notificación por correo electrónico, comprueba el log, corrige la aplicación y elimina el archivo de monitorización, lo que reactiva el envío de correos electrónicos.

Apertura en el editor

Al mostrar la página de error, se puede hacer clic en los nombres de los archivos y estos se abrirán en tu editor con el cursor en la línea correspondiente. También se pueden crear archivos (acción create file) o corregir errores en ellos (acción fix it). Para que esto funcione, es suficiente configurar el navegador y el sistema.

Versiones de PHP soportadas

Tracy compatible con PHP
Tracy 2.10 – 3.0 PHP 8.0 – 8.4
Tracy 2.9 PHP 7.2 – 8.2
Tracy 2.8 PHP 7.2 – 8.1
Tracy 2.6 – 2.7 PHP 7.1 – 8.0
Tracy 2.5 PHP 5.4 – 7.4
Tracy 2.4 PHP 5.4 – 7.2

Aplica a la última versión de parche.

Ports

Esta es una lista de ports no oficiales para otros frameworks y CMS: