Premiers pas avec Tracy
La bibliothèque Tracy est une aide quotidienne précieuse pour les programmeurs PHP. Elle vous aide à :
- détecter et corriger rapidement les erreurs
- journaliser les erreurs
- afficher le contenu des variables
- mesurer le temps d'exécution des scripts et des requêtes
- suivre la consommation de mémoire
PHP est un langage parfaitement adapté à la création d'erreurs difficiles à détecter, car il laisse aux développeurs une grande liberté. Un outil de débogage comme Tracy n'en a que plus de valeur. Il représente le nec plus ultra des outils de diagnostic pour PHP.
Si vous rencontrez Tracy pour la première fois aujourd'hui, croyez bien que votre vie va commencer à se diviser entre l'époque d'avant Tracy et l'époque avec elle. Bienvenue dans la meilleure des deux !
Installation
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 sinon télécharger le paquet entier ou le fichier tracy.phar.
Utilisation
Tracy s'active en appelant la méthode Tracy\Debugger::enable() le plus tôt possible au début du programme,
avant qu'aucune sortie ne soit envoyée :
use Tracy\Debugger;
require 'vendor/autoload.php'; // ou tracy.phar
Debugger::enable();
La première chose que vous remarquerez sur la page est la Tracy Bar, dans le coin inférieur droit. Si vous ne la voyez pas,
cela peut signifier que Tracy tourne en mode production. En effet, pour des raisons de sécurité, Tracy n'est visible que sur
localhost. Pour tester qu'elle fonctionne, vous pouvez la passer temporairement en mode développement à l'aide du paramètre
Debugger::enable(Debugger::Development).
Tracy Bar
La Tracy Bar est un panneau flottant affiché dans le coin inférieur droit de la page. Vous pouvez le déplacer à la souris et il retiendra sa position après le rechargement de la page.
Vous pouvez ajouter d'autres panneaux utiles à la Tracy Bar. Vous en trouverez d'intéressants dans les add-ons ou vous pouvez créer les vôtres.
Si vous ne voulez pas afficher la Tracy Bar, définissez :
Debugger::$showBar = false;
Visualisation des erreurs et des exceptions
Vous savez sûrement comment PHP signale les erreurs : il affiche quelque chose comme ceci dans le code source de la page :
Parse error: syntax error, unexpected '}' in HomePresenter.php on line 15
ou une 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/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 /sandbox/vendor/nette/utils/src/Utils/ObjectMixin.php on line 100
S'y retrouver dans une telle sortie n'a rien de facile. Si vous activez Tracy, les erreurs et les exceptions s'affichent sous une forme complètement différente :
Le message d'erreur crie littéralement. Vous voyez la partie du code source avec la ligne où l'erreur s'est produite mise en évidence. Le message Call to undefined method Nette\Http\User::isLogedIn() explique clairement l'erreur. Toute la page est interactive, vous pouvez cliquer pour obtenir plus de détails. Essayez.
Et devinez quoi ? Les erreurs fatales sont capturées et affichées de la même façon. Sans avoir à installer la moindre extension.
Des erreurs comme une faute de frappe dans un nom de variable ou une tentative d'ouvrir un fichier inexistant produisent des signalements de niveau E_NOTICE ou E_WARNING. On peut facilement les manquer dans la mise en page graphique, voire ne pas les voir du tout (à moins de regarder le code source). Laissez Tracy s'en charger :
Ou elles peuvent être affichées comme des erreurs :
Debugger::$strictMode = true; // affiche toutes les erreurs
Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // toutes les erreurs sauf les avertissements de dépréciation
Note : une fois activée, Tracy change le niveau de rapport d'erreurs en E_ALL. Si vous voulez le modifier, faites-le après
l'appel à enable().
Mode développement et mode production
Comme vous le voyez, Tracy est plutôt bavarde, ce qui est appréciable en environnement de développement mais provoquerait une catastrophe sur le serveur de production. Aucune information de débogage ne doit y être affichée. Tracy dispose donc d'une détection automatique de l'environnement. Si l'exemple tourne sur un serveur en ligne, l'erreur sera journalisé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 par dump()
et, bien sûr, de tous les messages d'erreur générés par PHP. Si vous avez donc oublié un dump($obj) dans le
code, ne vous inquiétez pas : rien ne sera affiché sur le serveur de production.
Comment fonctionne la détection automatique du mode ? Le mode est celui de 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 (autrement dit
que son en-tête HTTP est absent). Sinon, elle tourne en mode production.
Si vous voulez activer le mode développement dans d'autres cas, par exemple pour des développeurs accédant depuis une
adresse IP précise, vous pouvez l'indiquer en paramètre de la méthode enable() :
Debugger::enable('23.75.345.200'); // vous pouvez aussi 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 depuis une adresse IP précise et disposant de ce jeton dans le cookie :
Debugger::enable('secret1234@23.75.345.200');
Vous pouvez aussi définir directement le mode développement/production à l'aide des constantes
Debugger::Development ou Debugger::Production passées en paramètre de la méthode
enable().
Si vous utilisez Nette Framework, regardez comment y définir le mode : il sera ensuite utilisé aussi pour Tracy.
Journalisation des erreurs
En mode production, Tracy journalise automatiquement toutes les erreurs et les exceptions attrapées dans un journal texte.
Pour que la journalisation fonctionne, vous devez indiquer le chemin absolu du répertoire de journalisation dans la variable
$logDirectory ou le passer en deuxième paramètre à la méthode enable() :
Debugger::$logDirectory = __DIR__ . '/log';
La journalisation des erreurs est extrêmement utile. Imaginez que tous les utilisateurs de votre application soient en réalité des bêta-testeurs qui font gratuitement un travail de premier ordre en trouvant des erreurs : il serait absurde de jeter leurs précieux rapports à la poubelle sans les remarquer.
Si vous avez besoin de journaliser vos propres messages ou des exceptions attrapées, utilisez la méthode
log() :
Debugger::log('Erreur inattendue'); // message texte
try {
criticalOperation();
} catch (Exception $e) {
Debugger::log($e); // journalise l'exception
// ou
Debugger::log($e, Debugger::ERROR); // envoie aussi une notification par e-mail
}
Si vous voulez que Tracy journalise 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 essentielle et il veut être informé
immédiatement de chaque nouvelle erreur. Tracy va dans ce sens : elle sait envoyer des notifications par e-mail pour les
nouvelles entrées du journal. La variable $email détermine où envoyer ces e-mails :
Debugger::$email = 'admin@example.com';
Si vous utilisez tout Nette Framework, vous pouvez définir cela et le reste dans le fichier de configuration.
Pour éviter d'inonder votre boîte mail, Tracy n'envoie qu'un seul message et crée un fichier email-sent.
Quand un développeur reçoit la notification par e-mail, il consulte le journal, corrige l'application et supprime le fichier de
surveillance email-sent. Cela réactive l'envoi d'e-mails.
Rapports en markdown
À côté de chaque log/exception-*.html, Tracy écrit un fichier .md frère au contenu identique en
markdown : le message, la pile d'appels et les extraits du code source. Ces fichiers sont créés sans condition, qu'un agent IA
travaille ou non avec l'application.
Leur but est le traitement en masse. Au lieu de cliquer un à un dans des centaines de rapports HTML, vous pouvez confier tout le répertoire de journalisation à un agent IA et le laisser comparer chaque rapport à l'état actuel du code et proposer des corrections.
Prise en charge des agents IA
Lorsqu'un agent IA pilote votre application dans un navigateur (Chrome DevTools MCP, Playwright, Puppeteer), Tracy le détecte
via la propriété JavaScript navigator.webdriver et envoie dans la console du navigateur une version markdown des
diagnostics essentiels, à côté de l'interface standard :
- BlueScreen – exception, pile d'appels et valeurs des variables envoyées à
console.error()à côté de l'écran rouge, aussi bien pour le rendu synchrone que pour les erreurs AJAX. - Tracy Bar – résumé markdown des principaux panneaux (SQL, Errors, Dumps) envoyé à
console.log(). Debugger::dump()– une variante en texte brut à côté de la sortie HTML habituelle, pour que les dumps ne se perdent pas dans la page.- Page 500 de production –
console.error()informe l'agent qu'une erreur est survenue et que les détails ont été journalisés sur le serveur.
La détection pose le cookie tracy-webdriver=1 ; vous pouvez le définir manuellement dans les DevTools pour
activer la sortie markdown depuis un navigateur ordinaire. L'activation de l'agent n'a aucune incidence sur les fichiers
.md écrits à côté de chaque log/exception-*.html : ceux-là sont produits sans condition et forment
la base du traitement en masse des journaux de production.
Les panneaux personnalisés de la Tracy Bar peuvent fournir leur propre markdown en implémentant getAgentInfo(). Pour les utilisateurs de Claude Code, le
plugin Nette contient la skill tracy-debugging, qui apprend à
l'agent à lire la sortie de Tracy depuis list_console_messages().
Ouvrir les fichiers dans l'éditeur
Lorsque la page d'erreur s'affiche, vous pouvez cliquer sur les noms de fichiers et ils s'ouvriront dans votre éditeur, le
curseur placé sur la ligne correspondante. Les fichiers peuvent aussi être créés (action create file) ou les bugs
y être corrigés (action fix it). Pour cela, 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.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 |
Vaut pour les dernières versions correctives.
Portages
Voici une liste de portages non officiels vers d'autres frameworks et CMS :
- Drupal 7
- Framework Laravel : recca0120/laravel-tracy, whipsterCZ/laravel-tracy
- OpenCart
- ProcessWire CMS/CMF
- Slim Framework
- Framework Symfony : kutny/tracy-bundle, VasekPurchart/Tracy-Blue-Screen-Bundle
- WordPress