Démarrage avec Tracy

PHP est un langage propice à la création d'erreurs difficiles à détecter, car il donne aux développeurs une grande liberté. L'outil de débogage Tracy est d'autant plus précieux. Parmi les outils de diagnostic pour PHP, il représente le summum absolu.

Si vous rencontrez Tracy pour la première fois aujourd'hui, croyez bien que votre vie va se diviser en celle avant Tracy et celle avec elle. Bienvenue dans la meilleure partie !

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 également télécharger le paquet complet sous forme de fichier tracy.phar.

Utilisation

Nous activons Tracy en appelant la méthode Tracy\Debugger::enable() le plus tôt possible au début du programme, avant d'envoyer toute sortie :

use Tracy\Debugger;

require 'vendor/autoload.php'; // ou 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, pour des raisons de sécurité, Tracy n'est visible que sur localhost. Pour tester si elle fonctionne, vous pouvez la basculer temporairement en mode développement à l'aide du paramètre Debugger::enable(Debugger::Development).

Barre Tracy

La barre Tracy est un panneau flottant qui s'affiche dans le coin inférieur droit de la page. Nous pouvons la déplacer avec la souris et elle se souviendra de sa position après le rechargement de la page.

Il est possible d'ajouter d'autres panneaux utiles à la barre Tracy. Vous en trouverez beaucoup dans les add-ons, ou vous pouvez même écrire les vôtres.

Si vous ne souhaitez pas afficher la barre Tracy, définissez :

Debugger::$showBar = false;

Visualisation des erreurs et exceptions

Vous savez sûrement bien 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 lors d'une exception non intercepté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

Il n'est pas vraiment facile de s'orienter dans un tel affichage. Si nous activons Tracy, l'erreur ou l'exception s'affiche sous une forme complètement différente :

Le message d'erreur crie littéralement. Nous voyons une partie du code source avec la ligne surlignée où l'erreur s'est produite et l'information Call to undefined method Nette\Http\User::isLogedIn() explique clairement de quelle erreur il s'agit. De plus, toute la page est interactive, nous pouvons cliquer pour obtenir plus de détails. Essayez.

Et vous savez quoi ? De cette manière, elle intercepte et affiche même les erreurs fatales. Sans avoir besoin d'installer la moindre extension.

Les erreurs comme une faute de frappe dans le nom d'une variable ou une tentative d'ouvrir un fichier inexistant génèrent des messages de niveau E_NOTICE ou E_WARNING. Celles-ci peuvent être facilement négligées dans l'interface graphique de la page, voire ne pas être visibles du tout (sauf en regardant le code source de la page).

Ou elles peuvent être affichées de la même manière que les erreurs :

Debugger::$strictMode = true; // affiche toutes les erreurs
Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // toutes les erreurs sauf les notifications de dépréciation

Note : Tracy, après activation, change le niveau de rapport d'erreurs à E_ALL. Si vous souhaitez modifier cette valeur, faites-le après l'appel de enable().

Mode développeur vs mode production

Comme vous pouvez le voir, Tracy est assez bavarde, ce qui peut être apprécié dans un environnement de développement, alors que sur un serveur de production, cela provoquerait une véritable catastrophe. En effet, aucune information de débogage ne doit y être affichée. Tracy dispose donc d'une autodétection de l'environnement et si l'exemple est exécuté sur un serveur de production, l'erreur sera journalisée au lieu d'être affichée et le visiteur ne verra qu'un message compréhensible par l'utilisateur :

Le mode production supprime l'affichage de toutes les informations de débogage que nous envoyons via dump(), et bien sûr aussi de tous les messages d'erreur générés par PHP. Donc, si vous avez oublié quelques dump($obj) dans le code, ne vous inquiétez pas, rien ne sera affiché sur le serveur de production.

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

Si nous voulons activer le mode développeur dans d'autres cas, par exemple pour les programmeurs accédant depuis une adresse IP spécifique, nous l'indiquons comme paramètre de la méthode enable() :

Debugger::enable('23.75.345.200'); // il est possible d'indiquer aussi un tableau d'adresses IP

Nous recommandons vivement de combiner l'adresse IP avec un cookie. Dans le cookie tracy-debug, nous stockons un jeton secret, par ex. secret1234, et de cette manière, nous activons le mode développeur uniquement pour les programmeurs accédant depuis une adresse IP spécifique et qui ont le jeton mentionné dans le cookie :

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

Nous pouvons également définir directement le mode développeur/production en utilisant la constante Debugger::Development ou Debugger::Production comme paramètre de la méthode enable().

Si vous utilisez Nette Framework, regardez comment définir le mode pour celui-ci et celui-ci sera ensuite utilisé également pour Tracy.

Logging des erreurs

En mode production, Tracy enregistre automatiquement toutes les erreurs et exceptions interceptées dans un journal texte. Pour que le logging puisse avoir lieu, nous devons définir le chemin absolu vers le répertoire de logs dans la variable $logDirectory ou le passer comme second paramètre de la méthode enable() :

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

Le logging des erreurs est extrêmement utile. Imaginez que tous les utilisateurs de votre application sont en fait des bêta-testeurs qui effectuent gratuitement un travail de pointe pour trouver des erreurs, et vous feriez une bêtise si vous jetiez leurs précieux rapports sans y prêter attention à la poubelle.

Si nous avons besoin de journaliser notre propre message ou une exception que nous avons interceptée, nous utilisons pour cela la méthode log() :

Debugger::log('Une erreur inattendue s\'est produite'); // message texte

try {
	operationCritique();
} catch (Exception $e) {
	Debugger::log($e); // il est possible de journaliser aussi une exception
	// ou
	Debugger::log($e, Debugger::ERROR); // envoie également 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'informations clé et il veut être informé immédiatement de chaque nouvelle erreur. Tracy lui vient en aide, car elle peut informer d'une nouvelle entrée dans le journal par e-mail. Où envoyer les e-mails est déterminé par la variable $email :

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

Si vous utilisez l'ensemble du Nette Framework, ceci et d'autres paramètres peuvent être définis dans le fichier de configuration.

Cependant, pour ne pas inonder votre boîte e-mail, elle n'envoie toujours qu'un seul message et crée un fichier email-sent. Le développeur, après avoir reçu la notification par e-mail, vérifie le journal, corrige l'application et supprime le fichier de surveillance, ce qui réactive l'envoi d'e-mails.

Ouverture dans l'éditeur

Lors de l'affichage de la page d'erreur, il est possible de cliquer sur les noms de fichiers et ceux-ci 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 que cela fonctionne, il suffit de configurer le navigateur et le système.

Versions PHP supportées

Valable pour la dernière version patch.

Ports

Ceci est une liste de ports non officiels pour 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