はじめに

PHPは、開発者にかなりの自由度を与えるため、発見しにくいエラーを作成するのに適した言語です。それだけに、デバッグツールTracyは価値があります。PHPの診断ツールの中で、絶対的な最高峰を表しています。

もし今日Tracyに初めて出会うなら、あなたの人生はTracy以前とTracyと共にに分かれ始めるでしょう。より良い部分へようこそ！

インストール

Tracyをインストールする最良の方法は、最新のパッケージをダウンロードするか、Composerを使用することです：

composer require tracy/tracy

tracy.phar ファイルとして完全なパッケージをダウンロードすることもできます。

使用法

Tracyは、プログラムの開始時にできるだけ早く、いかなる出力も送信する前に Tracy\Debugger::enable() メソッドを呼び出すことで有効化します：

use Tracy\Debugger;

require 'vendor/autoload.php'; // または tracy.phar

Debugger::enable();

ページ上で最初に気づくことは、右下隅にあるTracy Barです。もしそれが見えない場合、Tracyが本番モードで実行されていることを意味するかもしれません。 Tracyはセキュリティ上の理由から、localhost上でのみ表示されます。機能するかどうかをテストするために、Debugger::enable(Debugger::Development) パラメータを使用して一時的に開発モードに切り替えることができます。

Tracy Bar

Tracy Barは、ページの右下隅に表示されるフローティングパネルです。マウスで移動でき、ページを再読み込みした後もその位置を記憶します。

Tracy Barには、その他の便利なパネルを追加できます。多くは アドオン で見つけることができ、自分で作成することもできます。

Tracy Barを表示したくない場合は、次のように設定します：

Debugger::$showBar = false;

エラーと例外の視覚化

PHPがどのようにエラーを通知するか、きっとよくご存知でしょう：ページのソースコードにこのようなものを出力します：

Parse error:  syntax error, unexpected '}' in HomePresenter.php on line 15

またはキャッチされなかった例外の場合：

Fatal error:  Uncaught Nette\MemberAccessException: Call to undefined method Nette\Application\UI\Form::addTest()? in /sandbox/vendor/nette/utils/src/Utils/ObjectMixin.php:100
Stack trace:
#0 /sandbox/vendor/nette/utils/src/Utils/Object.php(75): Nette\Utils\ObjectMixin::call(Object(Nette\Application\UI\Form), 'addTest', Array)
#1 /sandbox/app/Forms/SignFormFactory.php(32): Nette\Object->__call('addTest', Array)
#2 /sandbox/app/Presentation/Sign/SignPresenter.php(21): App\Forms\SignFormFactory->create()
#3 /sandbox/vendor/nette/component-model/src/ComponentModel/Container.php(181): App\Presentation\Sign\SignPresenter->createComponentSignInForm('signInForm')
#4 /sandbox/vendor/nette/component-model/src/ComponentModel/Container.php(139): Nette\ComponentModel\Container->createComponent('signInForm')
#5 /sandbox/temp/cache/latte/15206b353f351f6bfca2c36cc.php(17): Nette\ComponentModel\Co in /sandbox/vendor/nette/utils/src/Utils/ObjectMixin.php on line 100

このような出力では、理解するのは必ずしも簡単ではありません。Tracyを有効にすると、エラーまたは例外はまったく異なる形式で表示されます：

エラーメッセージは文字通り叫んでいます。エラーが発生した場所で強調表示された行を含むソースコードの一部と、*Call to undefined method Nette\Http\User::isLogedIn()* という情報が、どのようなエラーであるかを分かりやすく説明しています。ページ全体がさらにインタラクティブで、クリックしてより詳細な情報へ進むことができます。試してみてください。

そして、ご存知ですか？この方法で、致命的なエラーもキャッチして表示します。いかなる拡張機能もインストールする必要なく。

変数名のタイプミスや存在しないファイルを開こうとする試みのようなエラーは、E_NOTICEまたはE_WARNINGレベルのメッセージを生成します。これらはページのグラフィック内で簡単に見落とすことができ、まったく見えないことさえあります（ページのコードを見ない限り）。

または、エラーと同様に表示されることもあります：

Debugger::$strictMode = true; // すべてのエラーを表示
Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // 非推奨の通知を除くすべてのエラー

注釈：Tracyは有効化後、エラー報告レベルをE_ALLに変更します。この値を変更したい場合は、enable() の呼び出し後に行ってください。

開発モード vs 本番モード

ご覧のとおり、Tracyはかなりおしゃべりです。これは開発環境では評価できますが、本番サーバーでは完全な災害を引き起こすでしょう。そこではデバッグ情報は出力してはなりません。そのためTracyは環境の自動検出機能を備えており、もし例を本番サーバー上で実行すると、エラーは表示される代わりにログに記録され、訪問者はユーザーフレンドリーなメッセージのみを見ることになります：

本番モードは、dump() を使用して私たちが外部に送信するすべてのデバッグ情報の表示を抑制し、そしてもちろん、PHPが生成するすべてのエラーメッセージも抑制します。もしコード内に何らかの dump($obj) を忘れてしまった場合でも、心配する必要はありません。本番サーバーでは何も出力されません。

モードの自動検出はどのように機能しますか？モードが開発モードになるのは、アプリケーションがlocalhost上で（つまりIPアドレス 127.0.0.1 または ::1）実行されており、プロキシが存在しない場合（つまりそのHTTPヘッダーがない場合）です。それ以外の場合は本番モードで実行されます。

開発モードを他のケースでも有効にしたい場合、例えば特定のIPアドレスからアクセスするプログラマーに、それを enable() メソッドのパラメータとして指定します：

Debugger::enable('23.75.345.200'); // IPアドレスの配列を指定することもできます

IPアドレスとクッキーを組み合わせることを強く推奨します。tracy-debug クッキーに秘密のトークン、例えば secret1234 を保存し、この方法で特定のIPアドレスからアクセスし、クッキーに言及されたトークンを持っているプログラマー専用の開発モードを有効化します：

Debugger::enable('secret1234@23.75.345.200');

開発/本番モードは、定数 Debugger::Development または Debugger::Production を enable() メソッドのパラメータとして使用して直接設定することもできます。

Nette Frameworkを使用している場合、それに対するモードの設定方法 を確認してください。そしてそれはその後Tracyにも使用されます。

エラーロギング

本番モードでは、Tracyは自動的にすべてのエラーとキャッチされた例外をテキストログに記録します。ロギングが行われるためには、ログディレクトリへの絶対パスを変数 $logDirectory に設定するか、enable() メソッドの2番目のパラメータとして渡す必要があります：

Debugger::$logDirectory = __DIR__ . '/log';

エラーロギングは非常に便利です。想像してみてください。あなたのアプリケーションのすべてのユーザーが実際にはベータテスターであり、無料でエラー発見の優れた仕事を実行していること、そして、もし彼らの貴重なレポートを気づかずにゴミ箱に捨ててしまったら、あなたは愚かなことをするでしょう。

カスタムメッセージやあなたがキャッチした例外をログに記録する必要がある場合、そのためには log() メソッドを使用します：

Debugger::log('予期せぬエラーが発生しました'); // テキストメッセージ

try {
	kritickaOperace(); // クリティカルな操作
} catch (Exception $e) {
	Debugger::log($e); // 例外もログに記録できます
	// または
	Debugger::log($e, Debugger::ERROR); // Eメール通知も送信します
}

Tracyに E_NOTICE や E_WARNING のようなPHPエラーを詳細情報（HTMLレポート）付きでログ記録させたい場合は、Debugger::$logSeverity を設定してください：

Debugger::$logSeverity = E_NOTICE | E_WARNING;

真のプロフェッショナルにとって、エラーログは重要な情報源であり、すべての新しいエラーについてすぐに通知を受け取りたいと考えています。Tracyはその要望に応えます。なぜなら、ログの新しいエントリについてEメールで通知することができるからです。Eメールの送信先は変数 $email で指定します：

Debugger::$email = 'admin@example.com';

完全なNette Frameworkを使用している場合、これや他の設定を 設定ファイル で行うことができます。

しかし、あなたのEメール受信箱を溢れさせないために、常に1通のメッセージのみを送信し、email-sent ファイルを作成します。開発者はEメール通知を受け取った後、ログを確認し、アプリケーションを修正し、そして監視ファイルを削除します。これによりEメール送信が再び有効になります。

エディタで開く

エラーページが表示されたとき、ファイル名をクリックでき、そしてそれらはあなたのエディタでカーソルが該当する行にある状態で開かれます。ファイルを作成する（アクション create file）ことや、それらの中でエラーを修正する（アクション fix it）こともできます。これが機能するためには、ブラウザとシステムを設定する だけで十分です。

サポートされているPHPバージョン

最新のパッチバージョンに適用されます。

ポート

これは他のフレームワークやCMS用の非公式ポートのリストです：

• Drupal 7
• Laravel framework: recca0120/laravel-tracy, whipsterCZ/laravel-tracy
• OpenCart
• ProcessWire CMS/CMF
• Slim Framework
• Symfony framework: kutny/tracy-bundle, VasekPurchart/Tracy-Blue-Screen-Bundle
• Wordpress