Primeros pasos con Tracy

La librería Tracy es una ayuda útil para los programadores PHP. Le ayuda a:

  • detectar y corregir errores rápidamente
  • registrar errores
  • volcar variables
  • medir el tiempo de ejecución de scripts/consultas
  • ver el consumo de memoria

PHP es un lenguaje perfecto para cometer errores difícilmente detectables porque da una gran flexibilidad a los programadores. Tracy\Debugger es más valioso por eso. Es una herramienta definitiva entre las de diagnóstico.

Si conoces a Tracy por primera vez, créeme, tu vida empieza a dividirse en una antes de Tracy y otra con ella. ¡Bienvenido a la parte buena!

Instalación y requisitos

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

composer require tracy/tracy

También puede descargar el paquete completo o el archivo tracy.phar.

Utilización

Tracy se activa llamando al método `Tracy\Debugger::enable()' tan pronto como sea posible al principio del programa, antes de que se envíe ninguna salida:

use Tracy\Debugger;

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

Debugger::enable();

Lo primero que verá en la página es la barra de Tracy en la esquina inferior derecha. Si no la ves, puede significar que Tracy se está ejecutando en modo de producción. Esto se debe a que Tracy sólo es visible en localhost por razones de seguridad. Para probar si funciona, puede ponerlo temporalmente en modo de desarrollo utilizando el parámetro Debugger::enable(Debugger::Development).

Barra Tracy

La Tracy Bar es un panel flotante. Aparece en la esquina inferior derecha de una página. Puede moverla con el ratón. Recordará su posición tras la recarga de la página.

Puedes añadir otros paneles útiles a la Tracy Bar. Puedes encontrar algunos interesantes en addons o puedes crear los tuyos propios.

Si no desea mostrar Tracy Bar, configure:

Debugger::$showBar = false;

Visualización de Errores y Excepciones

Seguramente, usted sabe cómo PHP informa de los errores: hay algo como esto en el código fuente de la página:

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

o 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/presenters/SignPresenter.php(21): App\Forms\SignFormFactory->create()
#3 /sandbox/vendor/nette/component-model/src/ComponentModel/Container.php(181): App\Presenters\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

No es tan fácil navegar por esta salida. Si habilitas Tracy, tanto los errores como las excepciones se muestran de una forma completamente diferente:

El mensaje de error grita literalmente. Puede ver una parte del código fuente con la línea resaltada donde se ha producido el error. El mensaje explica claramente el error. Todo el sitio es interactivo, pruébelo.

¿Y sabe qué? Los errores fatales se capturan y muestran de la misma manera. No es necesario instalar ninguna extensión (haga clic para ver un ejemplo en vivo):

Errores como una errata en el nombre de una variable o un intento de abrir un archivo inexistente generan informes de nivel E_NOTICE o E_WARNING. Éstos pueden pasarse por alto fácilmente y/o quedar completamente ocultos en el diseño gráfico de una página web. Deje que Tracy los gestione:

O pueden mostrarse como errores:

Debugger::$strictMode = true; // display all errors
Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // all errors except deprecated notices

Nota: Tracy, cuando se activa, cambia el nivel de notificación de errores a E_ALL. Si desea cambiarlo, hágalo después de llamar a enable().

Modo de desarrollo frente a modo de producción

Como puedes ver, Tracy es bastante hablador, lo que puede apreciarse en el entorno de desarrollo, mientras que en el servidor de producción causaría un desastre. Eso es porque allí no debería mostrarse información de depuración. Por lo tanto, Tracy tiene autodetección de entorno y si el ejemplo se ejecuta en un servidor en vivo, el error se registrará en lugar de mostrarse, y el visitante sólo verá un mensaje amigable:

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

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

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

Debugger::enable('23.75.345.200'); // también puede proporcionar una serie de direcciones IP

Recomendamos encarecidamente combinar la dirección IP con una cookie. Almacene un token secreto, por ejemplo, secret1234, en la cookie tracy-debug, y de esta manera, active el modo de desarrollo sólo para los desarrolladores que accedan desde una dirección IP específica y que tengan el mencionado token en la cookie:

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

También puedes establecer directamente el modo desarrollo/producción utilizando las constantes Debugger::Development o Debugger::Production como parámetro del método enable().

Si utilizas el Nette Framework, echa un vistazo a cómo establecer el modo para él, y entonces también se utilizará para Tracy.

Registro de errores

En modo de producción, Tracy registra automáticamente todos los errores y excepciones en un registro de texto. Para que el registro tenga lugar, es necesario establecer la ruta absoluta al directorio de registro en la variable $logDirectory o pasarla como segundo parámetro al método enable():

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

El registro de errores es extremadamente útil. Imagina que todos los usuarios de tu aplicación son en realidad beta testers que hacen un trabajo de primera para encontrar errores de forma gratuita, y serías tonto si tiraras sus valiosos informes sin darte cuenta a la papelera.

Si necesita registrar sus propios mensajes o excepciones capturadas, utilice el método log():

Debugger::log('Unexpected error'); // text message

try {
	criticalOperation();
} catch (Exception $e) {
	Debugger::log($e); // log exception
	// or
	Debugger::log($e, Debugger::ERROR); // also sends an email notification
}

If you want Tracy to log PHP errors like E_NOTICE or E_WARNING with detailed information (HTML report), set Debugger::$logSeverity:

Debugger::$logSeverity = E_NOTICE | E_WARNING;

Para un verdadero profesional el registro de errores es una fuente crucial de información y quiere ser notificado sobre cualquier nuevo error inmediatamente. Tracy le ayuda. Ella es capaz de enviar un correo electrónico por cada nuevo registro de error. La variable $email identifica dónde enviar estos correos electrónicos:

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

Si utiliza todo el Nette Framework, puede establecer ésta y otras en el fichero de configuración.

Para proteger su buzón de correo electrónico de inundaciones, Tracy envía sólo un mensaje y crea un archivo email-sent. Cuando un desarrollador recibe la notificación por correo electrónico, comprueba el registro, corrige su aplicación y borra el archivo de seguimiento email-sent. Esto activa de nuevo el envío de e-mails.

Abrir archivos en el editor

Cuando se muestra la página de errores, puede hacer clic en los nombres de los archivos y se abrirán en su 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 ello, es necesario configurar el navegador y el sistema.

Versiones de PHP soportadas

Tracy compatible con PHP
Tracy 2.10 – 3.0 PHP 8.0 – 8.2
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

Se aplica a las últimas versiones de parches.

Puertos

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