変数のダンプ

デバッグをする人なら誰でも var_dump関数をご存じでしょう。変数の詳しい情報を出力してくれます。ただ残念なことに、その出力は HTML の整形がなく 1 行にまとまってしまいますし、HTML のエスケープの問題もあります。実務では var_dump をもっと便利な関数に置き換えたくなります。それが dump() です。

$arr = [10, 20.2, true, null, 'hello'];

dump($arr);
// または Debugger::dump($arr);

これは次の出力を生みます。

既定の明るいテーマは暗いテーマに変えられます。

Debugger::$dumpTheme = 'dark';

入れ子の深さは Debugger::$maxDepthで、表示される文字列の長さは Debugger::$maxLengthで、配列やオブジェクトの表示される要素の数は Debugger::$maxItemsで変えられます。当然ながら、小さい値にすると描画が速くなります。

Debugger::$maxDepth = 2; // 既定: 15
Debugger::$maxLength = 50; // 既定: 150
Debugger::$maxItems = 50; // 既定: 100

dump() 関数は、それが呼ばれた場所や、オブジェクトならそのクラスが定義されているファイルへのパスも表示できます。これは Debugger::$showLocationプロパティが決めます。

Debugger::$showLocation = true; // 場所の情報を表示します
Debugger::$showLocation = false; // 隠します

より細かく決めたいなら、Tracy\Dumper::dump() を直接呼び、Dumper::LOCATION オプションに Dumper::LOCATION_CLASS（クラスが定義されている場所だけ）か Dumper::LOCATION_SOURCE（dump() が呼ばれた場所も）を渡します。

dump() の実用的な仲間が dumpe()（dump & exit）と bdump() です。後者は変数の値を Tracy Bar のパネルにダンプできます。ダンプがページの見た目から離れるうえ、見出しも付けられるので、とても便利です。

bdump([2, 4, 6, 8], 'even numbers up to ten');
bdump([1, 3, 5, 7, 9], 'odd numbers up to ten');

Tracy\Dumper を直接使う

dump() の裏には Tracy\Dumper クラスがあり、これを直接使うこともできます。dump() と違って Debugger に頼らず、設定はすべてオプションの配列から取るので、単独のスクリプトや CLI の道具、あるいはダンプを文字列として欲しいときに便利です。設定が Debugger ではなく配列から来るので、既定値は少し違います。たとえば深さは 15 ではなく 7 です。

これらのメソッドはダンプを文字列として返します。

use Tracy\Dumper;

$html = Dumper::toHtml($var, [Dumper::DEPTH => 3]);  // ブラウザ向けの HTML
$text = Dumper::toText($var);                         // 平文。たとえばログ向け
$ansi = Dumper::toTerminal($var);                     // 端末向けの ANSI の色付きテキスト

あるいは Dumper::dump() で変数をそのまま出力します。これは環境に応じて HTML か端末向けの出力かを自動的に選びます。

Dumper::dump($var, [Dumper::DEPTH => 3]);

HTML の出力には小さなスタイルシートとスクリプトが要ります。Tracy が有効なアプリケーションの外で（つまり Debugger::enable() なしで）ダンプするときは、Dumper::renderAssets() でページの head に一度だけ出力してください。Dumper::dump() はこれを自分で行いますが、toHtml() は行いません。

オプション

出力は、上のすべてのメソッドに渡すオプションの配列が決めます。

オプション	説明	既定
`Dumper::DEPTH`	入れ子の深さの上限	`7`
`Dumper::TRUNCATE`	文字列の長さの上限	`150`
`Dumper::ITEMS`	配列やオブジェクトで表示される要素の数の上限	`100`
`Dumper::COLLAPSE`	最上位のノードを畳みますか。`true`/`false`、または要素がこの数以上になったら畳む	`14`
`Dumper::COLLAPSE_COUNT`	入れ子のノードを、要素がこの数以上になったら畳む	`7`
`Dumper::LOCATION`	場所を表示します。`true`/`false`、または `Dumper::LOCATION_CLASS`（クラスが定義されている場所だけ）か `Dumper::LOCATION_SOURCE`（呼び出しの場所も）	オフ
`Dumper::THEME`	色のテーマ。`light` か `dark`	`light`
`Dumper::HASH`	オブジェクトの ID（`#` の印）と参照（`&` の印）を表示しますか	`true`
`Dumper::DEBUGINFO`	オブジェクトのマジックメソッド `__debugInfo()` を使いますか	`false`
`Dumper::KEYS_TO_HIDE`	値を `*****` として隠すキーの名前の配列	`[]`
`Dumper::SCRUBBER`	機微な値に対して `true` を返すコールバック `fn(string $key, mixed $value, ?string $class): bool`	なし
`Dumper::OBJECT_EXPORTERS`	オブジェクトの独自の描画。下をご覧ください	`[]`

COLLAPSE、COLLAPSE_COUNT、THEME のオプションは、対話的な HTML の出力にだけ当てはまります。

SCRUBBER オプションはダンプから機微な値を隠します。完全な例は独自の Scrubberをご覧ください。

たとえばオブジェクトのハッシュのない、こぢんまりしたダンプを得るには次のようにします。

echo Dumper::toText($var, [Dumper::HASH => false]);

toTerminal() が使う ANSI の色は Dumper::$terminalColors で変えられます。

オブジェクトの独自の描画

既定では、ダンパーはオブジェクトをそのプロパティを並べる形で描きます。それがいちばん役に立つ見せ方とは限りません。たとえば PhpToken は、その種類を読める名前ではなく数の ID として見せます。Dumper::$objectExporters にエクスポーターを登録すれば、あるクラスをどう描くかをダンパーに教えられます。

use Tracy\Dumper;

Dumper::$objectExporters[PhpToken::class] = function (PhpToken $token, Dumper\Value $value): void {
	$value->value = $token->getTokenName() . ' ' . $token->text;
};

エクスポーターはオブジェクトと、それがどう見せられるかを表す Tracy\Dumper\Value オブジェクトを受け取ります。$value->value に代入すると、見出し（既定ではクラス名）があなたのテキストに置き換わるので、プロパティの一覧の代わりにこぢんまりした読みやすい表示になります。この設定は、そのクラスのすべてのダンプに、配列やほかのオブジェクトの中に入れ子になったものにも当てはまります。あるいは Tracy\Dumper::dump() の Dumper::OBJECT_EXPORTERS オプションで、その呼び出しにだけエクスポーターを渡せます。