Создание расширений для Tracy

Tracy предоставляет отличный инструмент для отладки вашего приложения. Однако иногда вам хотелось бы иметь под рукой и некоторую другую информацию. Мы покажем, как написать собственное расширение для Tracy Bar, чтобы сделать разработку еще приятнее.

  • Создание собственной панели для Tracy Bar
  • Создание собственного расширения для Bluescreen

Репозиторий готовых расширений для Tracy вы найдете на Componette.

Расширения для Tracy Bar

Создать новое расширение для Tracy Bar несложно. Вы создаете объект, реализующий интерфейс Tracy\IBarPanel, который имеет два метода: getTab() и getPanel(). Методы должны вернуть HTML-код вкладки (tab) (маленькая метка, отображаемая прямо на Baru) и панели. Если getPanel() ничего не возвращает, отобразится только сама метка. Если getTab() ничего не возвращает, ничего не отображается, и getPanel() больше не вызывается.

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

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

Регистрация

Регистрация выполняется с помощью Tracy\Bar::addPanel():

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

Или вы можете зарегистрировать панель прямо в конфигурации приложения:

tracy:
	bar:
		- ExamplePanel

HTML-код вкладки (tab)

Должен выглядеть примерно так:

<span title="Поясняющая метка">
	<svg>...</svg>
	<span class="tracy-label">Заголовок</span>
</span>

Изображение должно быть в формате SVG. Если поясняющая метка не нужна, <span> можно опустить.

HTML-код панели

Должен выглядеть примерно так:

<h1>Заголовок</h1>

<div class="tracy-inner">
<div class="tracy-inner-container">
	... содержимое ...
</div>
</div>

Заголовок должен быть либо таким же, как заголовок вкладки (tab), либо может содержать дополнительные данные.

Нужно учитывать, что одно расширение может зарегистрироваться несколько раз, например, с другими настройками, поэтому для стилизации нельзя использовать CSS id, а только class, и это в виде tracy-addons-<ИмяКласса>[-<необязательно>]. Затем запишите класс в div вместе с классом tracy-inner. При написании CSS полезно писать #tracy-debug .trida, потому что правило тогда имеет более высокий приоритет, чем reset.

Стили по умолчанию

В панели предварительно стилизованы <a>, <table>, <pre>, <code>. Если вы хотите создать ссылку, которая скрывает и показывает другой элемент, свяжите их атрибутами href и id и классом tracy-toggle:

<a href="#tracy-addons-ИмяКласса-{$counter}" class="tracy-toggle">Детали</a>

<div id="tracy-addons-ИмяКласса-{$counter}">...</div>

Если начальное состояние должно быть свернутым, добавьте обоим элементам класс tracy-collapsed.

Используйте статический счетчик (Counter), чтобы не создавались дублирующиеся ID на одной странице.

Расширение для Bluescreen

Таким образом можно добавлять собственные визуализации исключений или панели, которые отобразятся на bluescreen.

Расширение создается этой командой:

Tracy\Debugger::getBlueScreen()->addPanel(function (?Throwable $e) { // перехваченное исключение
	return [
		'tab' => '...Метка...',
		'panel' => '...HTML-код панели...',
	];
});

Функция вызывается дважды: сначала в параметре $e передается само исключение, и возвращенная панель отображается в начале страницы. Если ничего не возвращает, панель не отображается. Затем она вызывается с параметром null (в случае фатальной ошибки, которую нельзя перехватить как исключение), и возвращенная панель отображается под стеком вызовов (callstack). Если функция возвращает в массиве ключ 'bottom' => true, панель отображается в самом низу.