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

Activar Tracy es fácil. Simplemente añada estas dos líneas de código, preferiblemente justo después de cargar la librería (como require 'vendor/autoload.php') y antes de que cualquier salida sea enviada al navegador:

use Tracy\Debugger;

Debugger::enable();

Lo primero que verá en el sitio web es una barra de Tracy.

(Si no ve nada, significa que Tracy está funcionando en modo de producción. Por razones de seguridad, Tracy sólo es visible en localhost. Puede forzar la ejecución de Tracy en modo de desarrollo pasando Debugger::Development como primer parámetro del método enable() ).

El enable() implica cambiar el nivel de reporte de errores a E_ALL.

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 HomepagePresenter.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

Para detectar errores ortográficos al asignar a un objeto, utilizamos el trait Nette\SmartObject.

Modo de producción y registro de errores

Como puedes ver, Tracy es bastante elocuente. Se agradece en un entorno de desarrollo, pero en un servidor de producción causaría un desastre. Cualquier información de depuración no puede aparecer allí. Por lo tanto, Tracy tiene una funcionalidad de autodetección y registro del entorno. En lugar de mostrarse a sí misma, Tracy almacena la información en un archivo de registro y muestra al visitante un mensaje de error del servidor comprensible para el usuario:

El modo de salida de producción suprime toda la información de depuración que se envía a través de dump(), y por supuesto todos los mensajes de error generados por PHP. Así, incluso si olvida dump($obj) en el código fuente, no tiene que preocuparse por ello en su servidor de producción. No se verá nada.

El modo de salida se establece mediante el primer parámetro de Debugger::enable(). Puede especificar una constante Debugger::Production o Debugger::Development. Otra opción es configurarlo de forma que el modo de desarrollo se active cuando se acceda a la aplicación desde una dirección IP definida con un valor definido de cookie tracy-debug. La sintaxis utilizada para lograr esto es cookie-value@ip-address.

Si no se especifica, se utiliza el valor por defecto Debugger::Detect. En este caso, el sistema detecta un servidor por la dirección IP. Se elige el modo de producción si se accede a una aplicación a través de una dirección IP pública. Una dirección IP local conduce al modo de desarrollo. No es necesario configurar el modo en la mayoría de los casos. El modo se reconoce correctamente cuando se lanza la aplicación en el servidor local o en producción.

En el modo de producción, Tracy captura automáticamente todos los errores y excepciones en un registro de texto. A menos que especifique lo contrario, se almacenará en log/error.log. Este registro de errores es extremadamente útil. Imagine que todos los usuarios de su aplicación son betatesters. Están haciendo un trabajo de vanguardia de forma gratuita cuando cazan bugs y serías tonto si tiraras sus valiosos informes a una papelera de reciclaje sin darte cuenta.

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
}

Se puede establecer un directorio para el registro de errores mediante el segundo parámetro del método enable():

Debugger::enable(Debugger::Detect, __DIR__ . '/mylog');

Si desea que Tracy registre errores PHP como E_NOTICE o E_WARNING con información detallada (informe HTML), establezca 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 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: