Caution: The documentation you are viewing is for an older version of Zend Framework.
You can find the documentation of the current version at:
https://docs.zendframework.com/

概要 - Zend_Log

概要

Zend_Log は、ログ出力用の汎用コンポーネントです。複数のバックエンドに対応しており、ログに出力するメッセージをフォーマットしたり記録するメッセージをフィルタリングしたりできます。これらの関数は、以下のオブジェクトに分けられています。

ログ (Zend_Log のインスタンス) は、アプリケーション内でもっともよく使用するオブジェクトです。いくつでも望みの数だけのログオブジェクトを保持できます。それらが互いに影響しあうことはありません。ログオブジェクトには最低ひとつのライターが含まれる必要があり、オプションでひとつあるいは複数のフィルタを含むことができます。
ライター (Zend_Log_Writer_Abstract を継承したもの) は、データを保存する役割を受け持ちます。
フィルタ (Zend_Log_Filter_Interface を実装したもの) は、保存するログデータをブロックします。フィルタは個々のライターに適用することもできますし、ログに適用することもできます。ログに適用した場合は、すべてのライターの前に適用されます。どちらの場合についても、複数のフィルタを連結することが可能です。
フォーマッタ (Zend_Log_Formatter_Interface を実装したもの) は、ログのデータをライターに書き出す前に書式設定できます。個々のライターは、それぞれひとつのフォーマッタを保持しています。

ログの作成

ログの記録を開始するには、ライターのインスタンスを作成し、それをログのインスタンスに渡します。

$logger = new Zend_Log();
$writer = new Zend_Log_Writer_Stream('php://output');
 
$logger->addWriter($writer);

注意すべき点は、ログには最低ひとつのライターが必要であるということです。ライターはお好みの数だけ追加できます。追加するにはログの addWriter() メソッドを使用します。

一方、ログのコンストラクタで直接ライターを指定することも可能です。

$writer = new Zend_Log_Writer_Stream('php://output');
$logger = new Zend_Log($writer);

これで、ログが使用できるようになりました。

メッセージの記録

メッセージをログに記録するには、ログのインスタンスの log() メソッドを実行し、メッセージと優先度を渡します。

$logger->log('Informational message', Zend_Log::INFO);

log() メソッドの最初のパラメータは文字列の message で、二番目のパラメータは整数の priority です。優先度は、ログのインスタンスが理解できる形式の値のいずれかでなければなりません。これについては次の節で説明します。

こちらも別の方法が使用できます。 log() メソッドをコールするかわりに、優先度と同じ名前のメソッドをコールできます。

$logger->log('Informational message', Zend_Log::INFO);
$logger->info('Informational message');
 
$logger->log('Emergency message', Zend_Log::EMERG);
$logger->emerg('Emergency message');

ログの破棄

ログオブジェクトが不要になったら、ログオブジェクトを指す変数に NULL を代入してそれを破棄しましょう。これは、アタッチされている各ライターのインスタンスメソッド shutdown() をコールしてからログオブジェクトを破棄します。

$logger = null;

このように明示的にログを破棄することは必須ではありません。 PHP の終了時に、この処理が自動的に行われます。

組み込みの優先度の使用

Zend_Log クラスでは以下の優先度を定義しています。

EMERG   = 0;  // 緊急事態 (Emergency): システムが使用不可能です
ALERT   = 1;  // 警報 (Alert): 至急対応が必要です
CRIT    = 2;  // 危機 (Critical): 危機的な状況です
ERR     = 3;  // エラー (Error): エラーが発生しました
WARN    = 4;  // 警告 (Warning): 警告が発生しました
NOTICE  = 5;  // 注意 (Notice): 通常動作ですが、注意すべき状況です
INFO    = 6;  // 情報 (Informational): 情報メッセージ
DEBUG   = 7;  // デバッグ (Debug): デバッグメッセージ

これらの優先度は常に使用可能で、それぞれについて同じ名前のメソッドが用意されています。

これらの優先度は適当に指定しているわけではありません。もとは BSD の syslog プロトコルに由来するもので、 » RFC-3164 で示されています。それぞれの名前と優先度番号は、PHP におけるもうひとつのログ記録システムである » PEAR Log とも互換性があります。おそらく、これと Zend_Log は相互運用できるでしょう。

優先度の数値が小さいほど優先度が高くなります。EMERG (0) が最重要な優先度で、DEBUG (7) は組み込みの優先度の中ではもっとも優先度が低いものです。 DEBUG より低い優先度を定義することもできます。メッセージをログに記録する際には、この優先度の階層に注意し、適切なものを選択するようにしましょう。

ユーザ定義の優先度の追加

ユーザ定義の優先度を実行時に追加するには、ログの addPriority() メソッドを使用します。

$logger->addPriority('FOO', 8);

上の例では、新しい優先度 FOO を '8' という値で定義しています。これで、次のようにして新しい優先度でログ出力できるようになります。

$logger->log('Foo message', 8);
$logger->foo('Foo Message');

新しい優先度は、既存のものを上書きすることはできません。

ログのイベントについて理解する

log() メソッドやその仲間をコールした際に、ログのイベントが作成されます。これは単純な連想配列で、ライターに渡されるイベントの内容を表します。この配列には、 timestamp、message、priority および priorityName のキーが常に存在します。

event 配列の作成は完全に透過的です。しかし、event 配列について知っておかないと、上で示した既存のセットに含まれない項目を追加できません。

将来のイベントにたいして常に特定の項目を追加するようにするには、 setEventItem() メソッドをコールしてキーと値を指定します。

$logger->setEventItem('pid', getmypid());

上の例は、pid という名前の新しい項目を作成して現在のプロセスの PID を格納します。新しい値が設定されると、他のすべてのイベントデータと同様にすべてのライターから自動的にアクセス可能となります。項目を上書きするには、もう一度好きなときに setEventItem() メソッドをコールします。

新しいイベント項目を setEventItem() で設定すると、ロガーのすべてのライターに新しい項目を送信します。しかし、これはそれらのライターが実際にその項目を書き出すことを保証するものではありません。フォーマッタオブジェクトがその新しい項目のことを教えない限り、ライターはそれをどう扱っていいのかわからないからです。さらに詳しく学ぶには、フォーマッタの節を参照ください。

PHP のエラーを記録

Zend_Log は、PHP のエラーを記録するためにも使えます。 registerErrorHandler() を呼び出すと、現行のエラーハンドラの前に Zend_Log を追加して、同様に一緒にエラーを渡します。

PHP エラー由来の Zend_Log イベントには、 » set_error_handler 由来の handler ( int $errno , string $errstr [, string $errfile [, int $errline [, array $errcontext ]]] ) に一致する追加の項目があります

**PHP エラー由来の Zend_Log イベント用の追加項目**
名前	エラーハンドラ・パラメータ	説明
message	errstr	エラーメッセージ(文字列)
errno	errno	エラーの発生レベル(整数)
file	errfile	エラーが発生したファイル名(文字列)
line	errline	エラーが発生した行番号(整数)
context	errcontext	(任意) エラーが発生した場所のアクティブシンボルテーブルを指す配列。つまり、エラーが発生したスコープ内に存在するすべての変数の配列です。ユーザエラーハンドラは、決してエラーコンテキストを書き換えてはいけません。