Empezando con Tracy

*******************

<div class=perex>

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

</div>

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 |https://github.com/nette/tracy/releases], o usar Composer:

```shell

composer require tracy/tracy

```

También puedes descargar el paquete completo como un archivo [tracy.phar |https://github.com/nette/tracy/releases].

Uso

===

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

```php

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.

[* tracy-bar.webp *]:https://nette.github.io/tracy/tracy-debug-bar.html

Se pueden añadir otros paneles útiles a la Tracy Bar. Encontrarás muchos en los [complementos |https://componette.org], o incluso [puedes escribir los tuyos propios |extensions].

Si no quieres mostrar la Tracy Bar, configura:

```php

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:

/--pre .{font-size: 90%}

<b>Parse error</b>: syntax error, unexpected '}' in <b>HomePresenter.php</b> on line <b>15</b>

\--

o en caso de una excepción no capturada:

/--pre .{font-size: 90%}

<b>Fatal error</b>: 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 <b>/sandbox/vendor/nette/utils/src/Utils/ObjectMixin.php</b> on line <b>100</b><br />

\--

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:

[* tracy-exception.webp .{url:-} *]

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 |https://nette.github.io/tracy/tracy-exception.html].

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

[* tracy-error.webp .{url:-} *]

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

[* tracy-notice2.webp *]:https://nette.github.io/tracy/tracy-debug-bar.html

O pueden mostrarse igual que los errores:

```php

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

```

[* tracy-notice.webp .{url:-} *]

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:

[* tracy-error2.webp .{url:-} *]

El modo de producción suprime la visualización de toda la información de depuración que enviamos mediante [dump() |dumper], 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()`:

```php

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:

```php

Debugger::enable('[email protected]');

```

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()`.

.[note]

Si usas Nette Framework, consulta cómo [configurar el modo para él |application:bootstrapping#Modo de desarrollo vs producción] 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()`:

```php

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()`:

```php

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`:

```php

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:

```php

Debugger::$email = '[email protected]';

```

Si usas todo el Nette Framework, puedes configurar esto y otros ajustes en el [archivo de configuración |nette:configuring].

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 |open-files-in-ide].

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:

- [Drupal 7](https://www.drupal.org/project/traced)

- Laravel framework: [recca0120/laravel-tracy](https://github.com/recca0120/laravel-tracy), [whipsterCZ/laravel-tracy](https://github.com/whipsterCZ/laravel-tracy)

- [OpenCart](https://github.com/BurdaPraha/oc_tracy)

- [ProcessWire CMS/CMF](https://github.com/adrianbj/TracyDebugger)

- [Slim Framework](https://github.com/runcmf/runtracy)

- Symfony framework: [kutny/tracy-bundle](https://github.com/kutny/tracy-bundle), [VasekPurchart/Tracy-Blue-Screen-Bundle](https://github.com/VasekPurchart/Tracy-Blue-Screen-Bundle)

- [Wordpress](https://github.com/ktstudio/WP-Tracy)