Démarrer avec Tracy

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

L'activation de Tracy est facile. Il suffit d'ajouter ces deux lignes de code, de préférence juste après le chargement de la bibliothèque (comme require 'vendor/autoload.php') et avant que toute sortie soit envoyée au navigateur :

use Tracy\Debugger;

Debugger::enable();

La première chose que vous remarquerez sur le site Web est une barre Tracy.

(Si vous ne voyez rien, cela signifie que Tracy fonctionne en mode production. Pour des raisons de sécurité, Tracy n'est visible que sur localhost. Vous pouvez forcer Tracy à s'exécuter en mode développement en passant l'adresse Debugger::Development comme premier paramètre de la méthode enable() ).

L'adresse enable() implique de changer le niveau de rapport d'erreur en E_ALL.

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

Afin de détecter les fautes d'orthographe lors de l'affectation à un objet, nous utilisons le trait Nette\SmartObject.

Mode de production et journalisation des erreurs

Comme vous pouvez le constater, Tracy est assez éloquent. Elle est appréciée dans un environnement de développement, mais sur un serveur de production, elle provoquerait un désastre. Toute information de débogage ne peut y être répertoriée. C'est pourquoi Tracy dispose d'une fonctionnalité d'autodétection et de journalisation de l'environnement. Au lieu de se montrer, Tracy stocke les informations dans un fichier journal et montre au visiteur un message d'erreur du serveur compréhensible par l'utilisateur :

Le mode de sortie de production supprime toutes les informations de débogage qui sont envoyées via dump(), et bien sûr tous les messages d'erreur générés par PHP. Ainsi, même si vous oubliez dump($obj) dans le code source, vous n'avez pas à vous en soucier sur votre serveur de production. Rien ne sera vu.

Le mode de sortie est défini par le premier paramètre de Debugger::enable(). Vous pouvez spécifier une constante Debugger::Production ou Debugger::Development. Une autre option consiste à le configurer de telle sorte que le mode de développement soit activé lorsque l'application est accessible à partir d'une adresse IP définie avec une valeur définie du cookie tracy-debug. La syntaxe utilisée à cet effet est cookie-value@ip-address.

Si elle n'est pas spécifiée, la valeur par défaut Debugger::Detect est utilisée. Dans ce cas, le système détecte un serveur par adresse IP. Le mode production est choisi si une application est accessible via une adresse IP publique. Une adresse IP locale conduit au mode développement. Il n'est pas nécessaire de définir le mode dans la plupart des cas. Le mode est correctement reconnu lorsque vous lancez l'application sur votre serveur local ou en production.

En mode production, Tracy capture automatiquement toutes les erreurs et exceptions dans un journal texte. Sauf indication contraire de votre part, il sera stocké dans log/error.log. Cette journalisation des erreurs est extrêmement utile. Imaginez que tous les utilisateurs de votre application sont en fait des bêta-testeurs. Ils font un travail de pointe gratuitement en chassant les bogues et vous seriez stupide si vous jetiez leurs précieux rapports à la corbeille sans les remarquer.

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
}

Un répertoire pour la journalisation des erreurs peut être défini par le deuxième paramètre de la méthode enable() :

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

Si vous voulez que Tracy enregistre les erreurs PHP comme E_NOTICE ou E_WARNING avec des informations détaillées (rapport HTML), définissez 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

S'applique aux dernières versions des correctifs.

Ports

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

• Drupal 7
• Laravel framework: recca0120/laravel-tracy, whipsterCZ/laravel-tracy
• OpenCart
• ProcessWire CMS/CMF
• Slim Framework
• Symfony framework: kutny/tracy-bundle, VasekPurchart/Tracy-Blue-Screen-Bundle
• Wordpress