Tracy Extension'ları Yazma

Tracy için hazır extension'ların bulunduğu bir depoyu Componette adresinde bulabilirsiniz.

Tracy Bar Extension'ları

Tracy Bar için yeni bir extension yazmak dolaysızdır. Tracy\IBarPanel arayüzünü uygulayan bir nesne oluşturun; bu arayüzde iki metot vardır: getTab() ve getPanel(). Bu metotlar, sekmenin (doğrudan Bar üzerinde görünen küçük etiket) ve panelin (sekmeye tıklandığında açılan kutu) HTML kodunu döndürmelidir. getPanel() hiçbir şey döndürmezse yalnızca sekme görüntülenir. getTab() hiçbir şey döndürmezse hiçbir şey görüntülenmez ve getPanel() çağrılmaz.

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

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

Kayıt

Kayıt, Tracy\Debugger::getBar()->addPanel() çağrılarak yapılır:

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

Alternatif olarak paneli doğrudan uygulama yapılandırmasında kaydedebilirsiniz:

tracy:
	bar:
		- ExamplePanel

Sekmenin HTML Kodu

Şuna benzer görünmelidir:

<span title="Açıklayıcı ipucu">
	<svg>...</svg>
	<span class="tracy-label">Başlık</span>
</span>

Görsel SVG biçiminde olmalıdır. Açıklayıcı ipucu gerekmiyorsa dıştaki <span> atlanabilir.

Panelin HTML Kodu

Şuna benzer görünmelidir:

<h1>Başlık</h1>

<div class="tracy-inner">
<div class="tracy-inner-container">
	... içerik ...
</div>
</div>

Başlık ya sekmenin başlığıyla aynı olmalı ya da ek bilgi içermelidir.

Bir extension'ın belki farklı ayarlarla, birden çok kez kaydedilebileceğini unutmayın. Bu yüzden biçimlendirme için CSS ID'leri kullanamazsınız, yalnızca sınıflar kullanabilirsiniz; tercihen tracy-addons-<ClassName>[-<optional>] biçiminde. Bu sınıfı, tracy-inner sınıfıyla birlikte div'e ekleyin. CSS yazarken seçicilerin önüne #tracy-debug .your-class koymak yararlıdır; çünkü bu, kurala sıfırlama stillerinden daha yüksek özgüllük verir.

Varsayılan Stiller

Panelde <a>, <table>, <pre> ve <code> elemanlarının önceden tanımlı stilleri vardır. Başka bir elemanı gizleyip gösteren bir bağlantı oluşturmak isterseniz, onları href ve id nitelikleriyle ve tracy-toggle sınıfıyla bağlayın:

<a href="#tracy-addons-ClassName-{$counter}" class="tracy-toggle">Ayrıntılar</a>

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

Varsayılan durum katlanmışsa, her iki elemana da tracy-collapsed sınıfını ekleyin.

Bir sayfada yinelenen ID'leri önlemek için statik bir sayaç kullanın.

Özel Varlıklar

Panelinizin kendi stil sayfası ya da betiği gerekiyorsa, Tracy'nin kendi varlıklarının yanında ek dosyalar yüklemesini sağlayabilirsiniz:

Tracy\Debugger::$customCssFiles[] = __DIR__ . '/panel.css';
Tracy\Debugger::$customJsFiles[] = __DIR__ . '/panel.js';

Yapay Zekâ Ajanı Desteği

Bir yapay zekâ ajanı tarayıcıyı sürdüğünde Tracy, Tracy Bar'ın markdown özetini JS konsoluna gönderir. Özel paneller, IBarPanel gerçekleştirimlerine bir getAgentInfo(): ?string metodu ekleyerek kendi markdown çıktılarını sağlayabilir:

class DatabasePanel implements Tracy\IBarPanel
{
	public function getTab(): string { /* ... */ }
	public function getPanel(): string { /* ... */ }

	public function getAgentInfo(): ?string
	{
		return "## Database\n\n- Queries: {$this->count}\n- Total time: {$this->time} ms\n";
	}
}

Döndürülen markdown, çubuğun markdown özetine katılır. Metot yoksa ya da null döndürürse panel özetten çıkarılır.

Tam resim için bkz. Tracy'nin yapay zekâ ajanı tümleştirmesi.

Bluescreen Extension'ları

Bu şekilde, bluescreen'de görünecek özel istisna görselleştirmeleri ya da paneller ekleyebilirsiniz.

Bir extension şöyle oluşturulur:

Tracy\Debugger::getBlueScreen()->addPanel(function (?Throwable $e) { // yakalanan istisna
	return [
		'tab' => '...Başlık...',
		'panel' => '...panelin HTML içeriği...',
	];
});

Fonksiyon iki kez çağrılır. Önce $e parametresinde istisnanın kendisi aktarılır (bir istisna oluştuysa) ve döndürülen panel sayfanın başında render edilir. null ya da boş bir dizi döndürürse panel render edilmez. Sonra $e = null ile çağrılır ve döndürülen panel çağrı yığınının altında render edilir. Fonksiyon dizide 'bottom' => true döndürürse panel en altta render edilir.

Panellerin yanı sıra addAction() ile eylemler de ekleyebilirsiniz; bunlar hata sayfasının başlığında yerleşik olanların (örneğin search) yanında görünen tıklanabilir bağlantılar ya da düğmelerdir:

Tracy\Debugger::getBlueScreen()->addAction(function (Throwable $e): ?array {
	if ($e instanceof MyException) {
		return [
			'link' => 'https://example.com/help?code=' . $e->getCode(),
			'label' => 'yardımı gör',
		];
	}
	return null;
});

Callback, yakalanan istisnayı alır ve link ile label anahtarlarını içeren bir dizi ya da ilgili istisna için eylem eklemek istemiyorsa null döndürür.

Dosya Oluşturma Eylemi

Hata sayfasında henüz var olmayan bir dosyaya tıkladığınızda Tracy onu oluşturmayı önerir (create file eylemi). Böyle bir dosyanın başlangıç içeriğini bir üretici kaydederek denetleyebilirsiniz:

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, hedef dosya yolunu ve biliniyorsa içinde tanımlanması gereken sınıfın adını alır. Başlangıç içeriğini ($END$ belirteci imlecin konacağı yeri işaretler ve çıktıdan kaldırılır) ya da kararı başka bir üreticiye bırakmak için null döndürür. Üreticiler en son kaydedilenden başlayarak denenir; yerleşik üretici düz bir PHP iskeleti üretir.

Fiber'lar ve Generator'lar

Bir fiber ya da generator askıya alınmışken bir istisna fırlatılırsa, onun yığını sıradan çağrı yığınının parçası olmaz. Tracy, istisnadan ulaşılabilen fiber'ların ve generator'ların yığınını otomatik olarak gösterir, ama bağımsız çalışan biri gözden kaçardı. Onu BlueScreen'e elle ekleyebilirsiniz:

Tracy\Debugger::getBlueScreen()->addFiber($fiber);