Création d'extensions pour Tracy

Vous trouverez le dépôt des extensions Tracy prêtes à l'emploi sur Componette.

Extensions pour la barre Tracy

Créer une nouvelle extension pour la barre Tracy n'est pas compliqué. Vous créez un objet implémentant l'interface Tracy\IBarPanel, qui a deux méthodes getTab() et getPanel(). Les méthodes doivent retourner le code HTML de l'onglet (une petite étiquette affichée directement sur la barre) et du panneau. Si getPanel() ne retourne rien, seule l'étiquette elle-même sera affichée. Si getTab() ne retourne rien, rien ne sera affiché du tout et getPanel() ne sera même pas appelé.

class ExamplePanel implements Tracy\IBarPanel
{
	public function getTab()
	{
		return /* ... */;
	}

	public function getPanel()
	{
		return /* ... */;
	}
}

Enregistrement

L'enregistrement se fait via Tracy\Bar::addPanel() :

Tracy\Debugger::getBar()->addPanel(new ExamplePanel);

Ou vous pouvez enregistrer le panneau directement dans la configuration de l'application :

tracy:
	bar:
		- ExamplePanel

Code HTML de l'onglet

Il devrait ressembler approximativement à ceci :

<span title="Description explicative">
	<svg>...</svg>
	<span class="tracy-label">Titre</span>
</span>

L'image doit être au format SVG. Si la description explicative n'est pas nécessaire, le <span> peut être omis.

Code HTML du panneau

Il devrait ressembler approximativement à ceci :

<h1>Titre</h1>

<div class="tracy-inner">
<div class="tracy-inner-container">
	... contenu ...
</div>
</div>

Le titre doit être soit le même que le titre de l'onglet, soit il peut contenir des informations supplémentaires.

Il faut tenir compte du fait qu'une même extension peut être enregistrée plusieurs fois, par exemple avec des paramètres différents, il n'est donc pas possible d'utiliser des ID CSS pour le style, mais seulement des classes, et ce sous la forme tracy-addons-<NomDeLaClasse>[-<optionnel>]. Écrivez ensuite la classe dans le div avec la classe tracy-inner. Lors de l'écriture du CSS, il est utile d'écrire #tracy-debug .classe, car la règle a alors une priorité plus élevée que le reset.

Styles par défaut

Dans le panneau, <a>, <table>, <pre>, <code> sont pré-stylés. Si vous souhaitez créer un lien qui masque et affiche un autre élément, liez-les avec les attributs href et id et la classe tracy-toggle :

<a href="#tracy-addons-NomDeLaClasse-{$counter}" class="tracy-toggle">Détails</a>

<div id="tracy-addons-NomDeLaClasse-{$counter}">...</div>

Si l'état par défaut doit être réduit, ajoutez la classe tracy-collapsed aux deux éléments.

Utilisez un compteur statique pour éviter de créer des ID en double sur une même page.

Extensions pour Bluescreen

De cette manière, il est possible d'ajouter des visualisations personnalisées d'exceptions ou des panneaux qui s'afficheront sur le bluescreen.

L'extension est créée avec cette instruction :

Tracy\Debugger::getBlueScreen()->addPanel(function (?Throwable $e) { // exception interceptée
	return [
		'tab' => '...Étiquette...',
		'panel' => '...Code HTML du panneau...',
	];
});

La fonction est appelée deux fois, d'abord l'exception elle-même est passée dans le paramètre $e et le panneau retourné est affiché au début de la page. S'il ne retourne rien, le panneau n'est pas affiché. Ensuite, elle est appelée avec le paramètre null et le panneau retourné est affiché sous la pile d'appels (callstack). Si la fonction retourne la clé 'bottom' => true dans le tableau, le panneau est affiché tout en bas.