Tvorba rozšíření pro Tracy
**************************
<div class=perex>
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
</div>
.[tip]
Repozitář hotových rozšíření pro Tracy najdete na "Componette":https://componette.org/search/tracy.
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á.
```php
class ExamplePanel implements Tracy\IBarPanel
{
public function getTab()
{
return /* ... */;
}
public function getPanel()
{
return /* ... */;
}
}
```
Registrace
----------
Registrace se provádí pomocí `Tracy\Debugger::getBar()->addPanel()`:
```php
Tracy\Debugger::getBar()->addPanel(new ExamplePanel);
```
Nebo můžete panel registrovat přímo v konfiguraci aplikace:
```neon
tracy:
bar:
- ExamplePanel
```
HTML kód tabu
-------------
Měl by vypadat přibližně takto:
```latte
<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:
```latte
<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`:
```latte
<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:
```php
Tracy\Debugger::$customCssFiles[] = __DIR__ . '/panel.css';
Tracy\Debugger::$customJsFiles[] = __DIR__ . '/panel.js';
```
Podpora AI agentů .{data-version:2.12.0}
----------------------------------------
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`:
```php
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 |guide#Podpora AI agentů].
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:
```php
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*):
```php
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 .{data-version:2.9.0}
--------------------------------------------
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:
```php
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 .{data-version:2.9.2}
-----------------------------------------
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ě:
```php
Tracy\Debugger::getBlueScreen()->addFiber($fiber);
```
{{maintitle: Tvorba rozšíření pro Tracy: panely Baru a Bluescreen}}
{{description: Chcete mít při ladění po ruce další informace? Napište si vlastní panely pro Tracy Bar a vlastní sekce pro chybovou stránku Bluescreen v PHP.}}
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\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);