Tworzenie rozszerzeń dla Tracy

Repozytorium gotowych rozszerzeń dla Tracy znajdziesz na Componette.

Rozszerzenia dla Paska Tracy

Stworzenie nowego rozszerzenia dla Paska Tracy nie jest niczym skomplikowanym. Tworzysz obiekt implementujący interfejs Tracy\IBarPanel, który ma dwie metody getTab() i getPanel(). Metody muszą zwrócić kod HTML zakładki (mały opis wyświetlany bezpośrednio na Pasku) oraz panelu. Jeśli getPanel() nic nie zwróci, wyświetli się tylko sam opis. Jeśli getTab() nic nie zwróci, nie wyświetli się nic, a getPanel() nie zostanie już wywołane.

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

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

Rejestracja

Rejestrację przeprowadza się za pomocą Tracy\Bar::addPanel():

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

Lub możesz zarejestrować panel bezpośrednio w konfiguracji aplikacji:

tracy:
	bar:
		- ExamplePanel

Kod HTML zakładki

Powinien wyglądać mniej więcej tak:

<span title="Opis wyjaśniający">
	<svg>...</svg>
	<span class="tracy-label">Tytuł</span>
</span>

Obrazek powinien być w formacie SVG. Jeśli opis wyjaśniający nie jest potrzebny, można pominąć <span>.

Kod HTML panelu

Powinien wyglądać mniej więcej tak:

<h1>Tytuł</h1>

<div class="tracy-inner">
<div class="tracy-inner-container">
	... zawartość ...
</div>
</div>

Tytuł powinien być albo taki sam jak tytuł zakładki, albo może zawierać dodatkowe dane.

Należy wziąć pod uwagę, że jedno rozszerzenie może zostać zarejestrowane wielokrotnie, na przykład z innymi ustawieniami, więc do stylizacji nie można używać ID CSS, a jedynie klas, w formacie tracy-addons-<NazwaKlasy>[-<opcjonalne>]. Klasę należy następnie zapisać w elemencie div razem z klasą tracy-inner. Podczas pisania CSS przydatne jest pisanie #tracy-debug .klasa, ponieważ reguła ma wtedy wyższy priorytet niż reset.

Domyślne style

W panelu predefiniowane są style dla <a>, <table>, <pre>, <code>. Jeśli chcesz utworzyć link, który ukrywa i pokazuje inny element, połącz je atrybutami href i id oraz klasą tracy-toggle:

<a href="#tracy-addons-NazwaKlasy-{$counter}" class="tracy-toggle">Szczegóły</a>

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

Jeśli domyślny stan ma być zwinięty, dodaj obu elementom klasę tracy-collapsed.

Użyj statycznego licznika, aby uniknąć tworzenia zduplikowanych ID na jednej stronie.

Rozszerzenia dla Bluescreen

W ten sposób można dodawać własne wizualizacje wyjątków lub panele, które pojawią się na bluescreen.

Rozszerzenie tworzy się za pomocą tego polecenia:

Tracy\Debugger::getBlueScreen()->addPanel(function (?Throwable $e) { // przechwycony wyjątek
	return [
		'tab' => '...Etykieta...',
		'panel' => '...Kod HTML panelu...',
	];
});

Funkcja jest wywoływana dwukrotnie, najpierw w parametrze $e przekazywany jest sam wyjątek, a zwrócony panel jest renderowany na początku strony. Jeśli nic nie zwróci, panel nie zostanie wyrenderowany. Następnie jest wywoływana z parametrem null, a zwrócony panel jest renderowany pod stosem wywołań (callstack). Jeśli funkcja zwraca w tablicy klucz 'bottom' => true, panel zostanie wyrenderowany na samym dole.