Creación de extensiones para Tracy

Tracy proporciona una excelente herramienta para depurar tu aplicación. Sin embargo, a veces te gustaría tener a mano alguna información adicional. Te mostraremos cómo escribir tu propia extensión para la Tracy Bar, para que el desarrollo sea aún más agradable.

  • Creación de un panel personalizado para la Tracy Bar
  • Creación de una extensión personalizada para Bluescreen

Puedes encontrar un repositorio de extensiones listas para Tracy en Componette.

Extensiones para la Tracy Bar

Crear una nueva extensión para la Tracy Bar no es nada complicado. Creas un objeto que implemente la interfaz Tracy\IBarPanel, que tiene dos métodos getTab() y getPanel(). Los métodos deben devolver el código HTML de la pestaña (una pequeña etiqueta mostrada directamente en la Bar) y del panel. Si getPanel() no devuelve nada, solo se mostrará la etiqueta. Si getTab() no devuelve nada, no se mostrará nada en absoluto y getPanel() ya no se llamará.

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

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

Registro

El registro se realiza mediante Tracy\Bar::addPanel():

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

O puedes registrar el panel directamente en la configuración de la aplicación:

tracy:
	bar:
		- ExamplePanel

Código HTML de la pestaña

Debería verse aproximadamente así:

<span title="Descripción explicativa">
	<svg>...</svg>
	<span class="tracy-label">Título</span>
</span>

La imagen debe estar en formato SVG. Si no se necesita una descripción explicativa, se puede omitir el <span>.

Código HTML del panel

Debería verse aproximadamente así:

<h1>Título</h1>

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

El título debería ser el mismo que el título de la pestaña, o puede contener datos adicionales.

Hay que tener en cuenta que una extensión puede registrarse varias veces, por ejemplo, con diferentes configuraciones, por lo que para la estilización no se pueden usar IDs CSS, sino solo clases, y en la forma tracy-addons-<NombreClase>[-<opcional>]. Luego, escribe la clase en el div junto con la clase tracy-inner. Al escribir CSS, es útil escribir #tracy-debug .clase, porque la regla tendrá una prioridad más alta que el reset.

Estilos predeterminados

En el panel, <a>, <table>, <pre>, <code> están pre-estilizados. Si quieres crear un enlace que oculte y muestre otro elemento, conéctalos con los atributos href e id y la clase tracy-toggle:

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

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

Si el estado predeterminado debe ser colapsado, añade la clase tracy-collapsed a ambos elementos.

Usa un contador estático para evitar crear IDs duplicados en una página.

Extensiones para Bluescreen

De esta manera, se pueden añadir visualizaciones personalizadas de excepciones o paneles que se mostrarán en el bluescreen.

La extensión se crea con este comando:

Tracy\Debugger::getBlueScreen()->addPanel(function (?Throwable $e) { // excepción capturada
	return [
		'tab' => '...Etiqueta...',
		'panel' => '...Código HTML del panel...',
	];
});

La función se llama dos veces, primero se pasa la excepción misma en el parámetro $e y el panel devuelto se renderiza al principio de la página. Si no devuelve nada, el panel no se renderiza. Luego se llama con el parámetro null y el panel devuelto se renderiza debajo del callstack. Si la función devuelve en el array la clave 'bottom' => true, el panel se renderiza completamente abajo.