Tvorba rozšíření pro Tracy

Tracy poskytuje skvělý nástroj pro ladění vaší aplikace. Občas byste ale po ruce měli rádi i některé další informace. Ukážeme si, jak napsat vlastní rozšíření pro Tracy Bar, aby byl vývoj ještě příjemnější.

  • Vytvoření vlastního panelu pro Tracy Bar
  • Vytvoření vlastního rozšíření pro Bluescreen

Repozitář hotových rozšíření pro Tracy najdete na Componette.

Rozšíření pro Tracy Bar

Vytvořit nové rozšíření pro Tracy Bar není nic složitého. Vytvoříte objekt implementující rozhraní Tracy\IBarPanel, které má dvě metody getTab() a getPanel(). Metody musí vrátit HTML kód tabu (malý popisek zobrazený přímo na Baru) a panelu. Pokud getPanel() nic nevrátí, zobrazí se jen samotný popisek. Pokud getTab() nic nevrátí, nezobrazí se vůbec nic a ani getPanel() se už nevolá.

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

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

Registrace

Registrace se provádí pomocí Tracy\Bar::addPanel():

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

Nebo můžete panel registrovat přímo v konfiguraci aplikace:

tracy:
	bar:
		- ExamplePanel

HTML kód tabu

Měl by vypadat přibližně takto:

<span title="Vysvětlující popisek">
	<svg>...</svg>
	<span class="tracy-label">Titulek</span>
</span>

Obrázek by měl být ve formátu SVG. Pokud není vysvětlující popisek potřeba, lze <span> vynechat.

HTML kód panelu

Měl by vypadat přibližně takto:

<h1>Titulek</h1>

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

Titulek by měl být buď stejný, jako titulek tabu, nebo může obsahovat údaje navíc.

Je třeba počítat s tím, že jedno rozšíření se může zaregistrovat i vícekrát, kupříkladu s jiným nastavením, takže pro stylování nelze používat CSS id, ale jen class, a to ve tvaru tracy-addons-<NazevTridy>[-<volitelné>]. Třídu pak zapište do divu společně s třídou tracy-inner. Při zápisu CSS je užitečné psát #tracy-debug .trida, protože pravidlo pak má vyšší prioritu než reset.

Výchozí styly

V panelu jsou předstylované <a>, <table>, <pre>, <code>. Pokud chcete vytvořit odkaz, který skrývá a zobrazuje jiný prvek, propojte je atributy href a id a třídou tracy-toggle:

<a href="#tracy-addons-NazevTridy-{$counter}" class="tracy-toggle">Detaily</a>

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

Pokud má být výchozí stav sbalený, doplňte oběma elementům třídu tracy-collapsed.

Counter použijte statický, aby se nevytvářely duplicitní ID na jedné stránce.

Rozšíření pro Bluescreen

Tímto způsobem lze přidávat vlastní vizualizace výjimek nebo panely, které se zobrazí na bluescreen.

Rozšíření se vytvoří tímto příkazem:

Tracy\Debugger::getBlueScreen()->addPanel(function (?Throwable $e) { // zachycená výjimka
	return [
		'tab' => '...Popiska...',
		'panel' => '...HTML kod panelu...',
	];
});

Funkce je volána dvakrát, nejprve je v parametru $e předána samotná výjimka a vrácený panel se vykreslí na začátku stránky. Pokud nic nevrátí, panel se nevykreslí. Poté je volána s parametrem null a vrácený panel se vykreslí pod callstackem. Pokud funkce vrací v poli klíč 'bottom' => true, panel se vykreslí úplně dole.