Tracy の拡張を作る
************

<div class=perex>

Tracy はアプリケーションをデバッグする素晴らしい道具です。とはいえ、追加の情報をすぐ見られるようにしたいこともあります。ここでは Tracy Bar の独自の拡張を書いて、開発をいっそう心地よくする方法をお見せします。

- Tracy Bar の独自のパネルを作る
- BlueScreen の独自の拡張を作る

</div>

.[tip]
できあいの Tracy の拡張は "Componette":https://componette.org/search/tracy にそろっています。


Tracy Bar の拡張
=============

Tracy Bar の新しい拡張を作るのは簡単です。`Tracy\IBarPanel` インターフェースを実装するオブジェクトを作ります。このインターフェースには `getTab()` と `getPanel()` の 2 つのメソッドがあります。これらのメソッドは、タブ（Bar の上に直接表示される小さなラベル）とパネル（タブをクリックすると出てくるポップアップ）の HTML のコードを返さなければなりません。`getPanel()` が何も返さなければ、タブだけが表示されます。`getTab()` が何も返さなければ何も表示されず、`getPanel()` も呼ばれません。

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

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


登録
---

登録は `Tracy\Debugger::getBar()->addPanel()` を呼んで行います。

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

あるいはアプリケーションの設定でパネルを直接登録できます。

```neon
tracy:
	bar:
		- ExamplePanel
```


タブの HTML のコード
-------------

だいたい次のようになります。

```latte
<span title="Explanatory tooltip">
	<svg>...</svg>
	<span class="tracy-label">Title</span>
</span>
```

画像は SVG の形式にすべきです。説明のツールチップが要らなければ、外側の `<span>` は省けます。


パネルの HTML のコード
--------------

だいたい次のようになります。

```latte
<h1>Title</h1>

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

見出しはタブの見出しと同じにするか、追加の情報を含めるとよいでしょう。

ひとつの拡張が、違う設定で何度も登録されることがあるのを忘れないでください。ですからスタイルには CSS の ID は使えず、クラスだけを、できれば `tracy-addons-<ClassName>[-<optional>]` の形で使います。このクラスを `tracy-inner` クラスと一緒に div に足します。CSS を書くときは、セレクタに `#tracy-debug .your-class` の接頭辞を付けると便利です。そうすればリセットのスタイルより詳細度が高くなります。


既定のスタイル
-------

パネルの中では `<a>`、`<table>`、`<pre>`、`<code>` の要素にあらかじめスタイルが付いています。ほかの要素を隠したり見せたりするリンクを作りたいなら、`href` と `id` の属性、そして `tracy-toggle` クラスで結び付けます。

```latte
<a href="#tracy-addons-ClassName-{$counter}" class="tracy-toggle">Details</a>

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

既定で畳んだ状態にしたいなら、両方の要素に `tracy-collapsed` クラスを足します。

1 ページの中で ID が重ならないように、静的なカウンタを使ってください。


独自のアセット
-------

パネルに独自のスタイルシートやスクリプトが要るなら、Tracy に自分のアセットと一緒に追加のファイルを読み込ませられます。

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


AI エージェントへの対応 .{data-version:2.12.0}
------------------------------------

AI エージェントがブラウザを動かしているとき、Tracy は Tracy Bar の markdown の要約を JS のコンソールへ送ります。独自のパネルは、`IBarPanel` の実装に `getAgentInfo(): ?string` メソッドを足せば自分の markdown を出せます。

```php
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";
	}
}
```

返された markdown はバーの markdown の要約に含まれます。このメソッドがないか `null` を返す場合、そのパネルは要約から外されます。

全体像は [Tracy の AI エージェントとの統合 |guide#AI エージェントへの対応]をご覧ください。


BlueScreen の拡張
==============

このやり方で、青い画面に現れる独自の例外の見せ方やパネルを足せます。

拡張は次のように作ります。
```php
Tracy\Debugger::getBlueScreen()->addPanel(function (?Throwable $e) { // 捕まえた例外
	return [
		'tab' => '...Title...',
		'panel' => '...HTML panel content...',
	];
});
```

この関数は 2 回呼ばれます。まず（例外が起きていれば）例外そのものが `$e` パラメータに渡され、返されたパネルはページの先頭に描かれます。`null` か空の配列を返すと、そのパネルは描かれません。次に `$e = null` で呼ばれ、返されたパネルは呼び出しのスタックの下に描かれます。関数が配列で `'bottom' => true` を返すと、そのパネルはいちばん下に描かれます。

パネルのほかに、`addAction()` で**アクション**も足せます。これはエラーのページの見出しの部分に、組み込みのもの（*search* など）と並んで現れる、クリックできるリンクやボタンです。

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

このコールバックは捕まえた例外を受け取り、`link` と `label` のキーを持つ配列を返します。その例外にアクションを足したくなければ `null` を返します。


ファイルを作るアクション .{data-version:2.9.0}
----------------------------------

エラーのページでまだ存在しないファイルをクリックすると、Tracy はそれを作ることを申し出ます（*create file* の操作）。そのファイルの最初の中身は、生成器を登録すれば決められます。

```php
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;
});
```

このコールバックは対象のファイルのパスと、分かっていればそこで定義されるべきクラスの名前を受け取ります。そして最初の中身を返します（`$END$` のトークンはカーソルが置かれる場所を示し、出力からは取り除かれます）。判断をほかの生成器に任せたいなら `null` を返します。生成器は最後に登録されたものから順に試されます。組み込みの生成器はごく素朴な PHP の骨組みを作ります。


ファイバーとジェネレータ .{data-version:2.9.2}
----------------------------------

ファイバーやジェネレータが止まっているあいだに例外が投げられると、そのスタックはふつうの呼び出しのスタックの一部にはなりません。Tracy は例外からたどれるファイバーとジェネレータのスタックを自動的に見せますが、独立して動いているものは見落とされます。それは手で BlueScreen に足せます。

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