Creating Tracy Extensions

Tracy is a great tool for debugging your application. However, you sometimes need more information than Tracy offers. You'll learn about:

  • Creating your own Tracy Bar panels
  • Creating your own Bluescreen extensions

You can find useful extensions for Tracy on Componette.

Tracy Bar Extensions

Creating a new extension for Tracy Bar is simple. You need to implement Tracy\IBarPanel interface with methods getTab() and getPanel(). The methods must return the HTML code of a tab (small label on Tracy Bar) and a panel (pop-up displayed after clicking on the tab). If getPanel() returns nothing, only the tab will be displayed. If getTab() returns nothing, nothing is displayed and getPanel() will not be called.

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

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

Registration

Registration is done by calling Tracy\Bar::addPanel():

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

or you can simply register your panel in application configuration:

tracy:
	bar:
		- ExamplePanel

Tab HTML Code

Should look something like this:

<span title="Explaining tooltip">
	<svg>...</svg>
	<span class="tracy-label">Title</span>
</span>

Image should be in format SVG. If you don't need tooltip, you can leave <span> out.

Panel HTML Code

Should look something like this:

<h1>Title</h1>

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

Title should either be the same as in tab or contain additional information.

One extension can be registered multiple times, so it's recommended not to use id attribute for styling. You can use classes, preferably in tracy-addons-<class-name>[-<optional>] format. When creating CSS, it's better to use #tracy-debug .class, because such rule has a higher priority than reset.

Default Styles

In the panel, elements <a>, <table>, <pre>, <code> have default styles. For creating a link for hiding or displaying other element, connect them with href and id attributes and class tracy-toggle.

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

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

If the default state is collapsed, add class tracy-collapsed to both elements.

Use a static counter to prevent duplicate IDs on one page.

Bluescreen Extensions

You can add your own exception visualizations or panels, which will appear on the bluescreen.

Extension is made like this:

Tracy\Debugger::getBlueScreen()->addPanel(function (?Throwable $e) { // catched exception
	return [
		'tab' => '...Title...',
		'panel' => '...content...',
	];
});

The function is called twice, first the exception itself is passed in the $e parameter and the returned panel is rendered at the beginning of the page. If nothing is returned, the panel is not rendered. Then it is called with the null parameter and the returned panel is rendered below the callstack. If the function returns 'bottom' => true in the array, the panel is rendered at the very bottom.