Tvorba rozšíření pro Tracy

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\Debugger::getBar()->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.

Vlastní assety

Pokud váš panel potřebuje vlastní styl nebo skript, můžete nechat Tracy načíst další soubory společně s jejími vlastními assety:

Tracy\Debugger::$customCssFiles[] = __DIR__ . '/panel.css';
Tracy\Debugger::$customJsFiles[] = __DIR__ . '/panel.js';

Podpora AI agentů

Když prohlížeč ovládá AI agent, Tracy pošle markdown shrnutí Tracy Baru do JS konzole. Vlastní panely mohou nabídnout svůj markdown přidáním metody getAgentInfo(): ?string do třídy implementující IBarPanel:

class DatabasePanel implements Tracy\IBarPanel
{
	public function getTab(): string { /* ... */ }
	public function getPanel(): string { /* ... */ }

	public function getAgentInfo(): ?string
	{
		return "## Database\n\n- Dotazy: {$this->count}\n- Celkový čas: {$this->time} ms\n";
	}
}

Vrácený markdown se zařadí do markdown shrnutí baru. Pokud metoda chybí nebo vrátí null, panel se ve shrnutí vynechá.

Více v integraci Tracy s AI agenty.

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.

Kromě panelů lze pomocí addAction() přidávat i akce – klikací odkazy nebo tlačítka, která se objeví v hlavičce chybové stránky vedle vestavěných (jako je search):

Tracy\Debugger::getBlueScreen()->addAction(function (Throwable $e): ?array {
	if ($e instanceof MyException) {
		return [
			'link' => 'https://example.com/help?code=' . $e->getCode(),
			'label' => 'view help',
		];
	}
	return null;
});

Callback dostane zachycenou výjimku a vrátí pole s klíči link a label, nebo null, pokud pro danou výjimku akci přidávat nechce.

Akce vytvoření souboru

Když na chybové stránce kliknete na soubor, který ještě neexistuje, Tracy nabídne jeho vytvoření (akce create file). Výchozí obsah takového souboru můžete ovlivnit zaregistrováním generátoru:

Tracy\Debugger::getBlueScreen()->addFileGenerator(function (string $file, ?string $class): ?string {
	if (str_ends_with($file, 'Test.php')) {
		return "<?php\n\nclass $class extends Tester\\TestCase\n{\n\t\$END\$\n}\n";
	}
	return null;
});

Callback dostane cestu k cílovému souboru a, pokud je známý, název třídy, která v něm má být definována. Vrátí výchozí obsah (značka $END$ označuje, kam se umístí kurzor, a z výstupu se odstraní), nebo null, aby rozhodnutí přenechal jinému generátoru. Generátory se zkoušejí od naposledy zaregistrovaného; vestavěný generátor vytvoří prostou PHP kostru.

Fibery a generátory

Pokud je výjimka vyhozena v okamžiku, kdy je fiber nebo generátor pozastavený, jeho zásobník není součástí běžného callstacku. Tracy automaticky zobrazí zásobník fiberů a generátorů dosažitelných z výjimky, ale ten běžící samostatně by chyběl. Na BlueScreen jej můžete přidat ručně:

Tracy\Debugger::getBlueScreen()->addFiber($fiber);