Démarrer avec Tracy

La bibliothèque Tracy est une aide utile pour les programmeurs PHP de tous les jours. Elle vous aide à :

  • détecter et corriger rapidement les erreurs
  • enregistrer les erreurs
  • vider les variables
  • mesurer le temps d'exécution des scripts/requêtes
  • voir la consommation de mémoire

PHP est un langage parfait pour faire des erreurs difficilement détectables car il offre une grande flexibilité aux programmeurs. Tracy\Debugger est plus précieux pour cette raison. C'est un outil ultime parmi les outils de diagnostic.

Si vous rencontrez Tracy pour la première fois, croyez-moi, votre vie commence à être divisée en une avant Tracy et une avec elle. Bienvenue dans la bonne partie !

Installation et conditions requises

La meilleure façon d'installer Tracy est de télécharger le dernier paquet ou d'utiliser Composer :

composer require tracy/tracy

Vous pouvez également télécharger le paquet complet ou le fichier tracy.phar.

Utilisation

Tracy est activé en appelant la méthode `Tracy\Debugger::enable()' dès que possible au début du programme, avant que toute sortie ne soit envoyée :

use Tracy\Debugger;

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

Debugger::enable();

La première chose que vous remarquerez sur la page est la barre Tracy dans le coin inférieur droit. Si vous ne la voyez pas, cela peut signifier que Tracy fonctionne en mode production. En effet, Tracy n'est visible que sur localhost pour des raisons de sécurité. Pour tester son fonctionnement, vous pouvez le mettre temporairement en mode développement en utilisant le paramètre Debugger::enable(Debugger::Development).

Barre Tracy

La barre Tracy est un panneau flottant. Elle s'affiche dans le coin inférieur droit d'une page. Vous pouvez la déplacer à l'aide de la souris. Elle se souviendra de sa position après le rechargement de la page.

Vous pouvez ajouter d'autres panneaux utiles à la barre Tracy. Vous pouvez en trouver des intéressants dans les addons ou vous pouvez créer les vôtres.

Si vous ne voulez pas afficher Tracy Bar, réglez :

Debugger::$showBar = false;

Visualisation des erreurs et des exceptions

Vous savez certainement comment PHP signale les erreurs : il y a quelque chose comme ceci dans le code source de la page :

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

ou exception non attrapée :

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

Il n'est pas si facile de naviguer dans cette sortie. Si vous activez Tracy, les erreurs et les exceptions sont affichées sous une forme complètement différente :

Le message d'erreur est littéralement criant. Vous pouvez voir une partie du code source avec la ligne surlignée où l'erreur s'est produite. Un message explique clairement une erreur. L'ensemble du site est interactif, essayez-le.

Et vous savez quoi ? Les erreurs fatales sont capturées et affichées de la même manière. Il n'est pas nécessaire d'installer une quelconque extension (cliquez pour voir un exemple en direct) :

Les erreurs telles qu'une faute de frappe dans un nom de variable ou une tentative d'ouverture d'un fichier inexistant génèrent des rapports de niveau E_NOTICE ou E_WARNING. Ces erreurs peuvent être facilement négligées et/ou peuvent être complètement cachées dans la mise en page graphique d'une page Web. Laissez Tracy les gérer :

Ou ils peuvent être affichés comme des erreurs :

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

Note : Tracy, lorsqu'il est activé, fait passer le niveau de signalement des erreurs à E_ALL. Si vous souhaitez modifier ce niveau, faites-le après avoir appelé enable().

Mode développement ou mode production

Comme vous pouvez le constater, Tracy est assez bavard, ce qui peut être apprécié dans l'environnement de développement, alors que sur le serveur de production, cela provoquerait un désastre. En effet, aucune information de débogage ne doit y être affichée. Tracy dispose donc d'une détection automatique de l'environnement et si l'exemple est exécuté sur un serveur en production, l'erreur sera enregistrée au lieu d'être affichée, et le visiteur ne verra qu'un message convivial :

Le mode production supprime l'affichage de toutes les informations de débogage envoyées à l'aide de dump(), et bien sûr de tous les messages d'erreur générés par PHP. Ainsi, si vous avez oublié quelques dump($obj) dans le code, vous n'avez pas à vous inquiéter, rien ne sera affiché sur le serveur de production.

Comment fonctionne l'autodétection du mode ? Le mode est développement si l'application tourne sur localhost (c'est-à-dire l'adresse IP 127.0.0.1 ou ::1) et qu'il n'y a pas de proxy (c'est-à-dire son en-tête HTTP). Sinon, elle s'exécute en mode production.

Si vous souhaitez activer le mode développement dans d'autres cas, par exemple pour les développeurs accédant à partir d'une adresse IP spécifique, vous pouvez le spécifier en tant que paramètre de la méthode enable():

Debugger::enable('23.75.345.200'); // vous pouvez également fournir un tableau d'adresses IP

Nous recommandons vivement de combiner l'adresse IP avec un cookie. Stockez un jeton secret, par exemple secret1234, dans le cookie tracy-debug, et activez ainsi le mode développement uniquement pour les développeurs accédant à partir d'une adresse IP spécifique qui ont le jeton mentionné dans le cookie :

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

Vous pouvez également définir directement le mode développement/production en utilisant les constantes Debugger::Development ou Debugger::Production comme paramètre de la méthode enable().

Si vous utilisez le Nette Framework, jetez un coup d'œil à la manière de définir le mode pour celui-ci, et il sera alors également utilisé pour Tracy.

Enregistrement des erreurs

En mode production, Tracy enregistre automatiquement toutes les erreurs et exceptions dans un journal texte. Pour que la journalisation ait lieu, vous devez définir le chemin absolu vers le répertoire de journalisation dans la variable $logDirectory ou le transmettre en tant que deuxième paramètre de la méthode enable():

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

La journalisation des erreurs est extrêmement utile. Imaginez que tous les utilisateurs de votre application sont en fait des bêta-testeurs qui font un excellent travail en trouvant des erreurs gratuitement, et vous seriez stupide de jeter leurs précieux rapports à la poubelle sans vous en rendre compte.

Si vous avez besoin de consigner vos propres messages ou les exceptions capturées, utilisez la méthode 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;

Pour un vrai professionnel, le journal des erreurs est une source d'information cruciale et il veut être informé immédiatement de toute nouvelle erreur. Tracy l'aide. Elle est capable d'envoyer un e-mail pour chaque nouvel enregistrement d'erreur. La variable $email identifie l'endroit où envoyer ces e-mails :

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

Si vous utilisez l'ensemble du Nette Framework, vous pouvez définir cette variable et d'autres dans le fichier de configuration.

Pour protéger votre boîte aux lettres électronique d'une inondation, Tracy envoie un seul message et crée un fichier email-sent. Lorsqu'un développeur reçoit la notification par e-mail, il vérifie le journal, corrige son application et supprime le fichier de surveillance email-sent. Cela active à nouveau l'envoi d'e-mails.

Ouverture de fichiers dans l'éditeur

Lorsque la page d'erreur est affichée, vous pouvez cliquer sur les noms de fichiers et ils s'ouvriront dans votre éditeur avec le curseur sur la ligne correspondante. Il est également possible de créer des fichiers (action create file) ou d'y corriger des erreurs (action fix it). Pour ce faire, vous devez configurer le navigateur et le système.

Versions de PHP prises en charge

Tracy compatible avec 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

S'applique aux dernières versions des correctifs.

Ports

C'est une liste de ports non officiels vers d'autres frameworks et CMS :