PSR-3ログインタフェース仕様

ログインタフェース仕様
ログクラスライブラリの汎用インタフェース仕様を策定した.
本仕様の主な目的は、ログクラスライブラリを単純に汎用的に、Psr\Log\LoggerInterfaceオブジェクトを受信することによって、ログ情報を記録することである.フレームワークおよびCMSコンテンツ管理システムは、必要に応じてこのインタフェースを拡張できますが、サードパーティのクラスライブラリファイルを使用してもログインタフェースが正常に接続されることを保証するには、本仕様に従う必要があります.
「能願動詞」の使用について
曖昧さを避けるため、文書には「能願動詞」が多く使われており、対応する解釈は以下の通りである.

(MUST):絶対、厳格に従い、そのとおりにしてください.無条件に守ってください.

(MUST NOT):禁令、厳令禁止;

(SHOULD):強く提案しますが、強要しません.

(SHOULD NOT):強くお勧めしませんが、強要しません.

(MAY)と (OPTIONAL):選択性が高く、このドキュメントでは、この語の使用が少ない.

参照:RFC 2119
1.仕様説明
1.1基本規範

LoggerInterfaceインタフェースは、RFC 5424で定義された8つのレベルのログ:debug、info、notice、warning、error、critical、alert、およびemergencyを記録するためにそれぞれ使用される8つの方法を対外的に定義している.

第9の方法であるlogは、第1のパラメータが記録されたレベルである.このメソッドは、パラメータとして予め定義された等級定数を使用して呼び出すことができ、以上の8つのメソッドを直接呼び出すのと同じ効果を持つ必要があります.入力された等級定数パラメータが予め定義されていない場合、Psr\Log\InvalidArgumentExceptionタイプの例外を放出する必要があります.不確定な場合、使用者はサポートされていない等級定数を使用してこの方法を呼び出すべきではない.

1.2記録情報

以上の各メソッドは、1つの文字列タイプまたは__toString()メソッドのオブジェクトを記録情報パラメータとして受け入れる.これにより、実装者はそれを文字列として処理することができ、そうしないと、実装者は自分で文字列に変換しなければならない.

レコード情報パラメータは、プレースホルダを運ぶことができ、インプリメンテーションは、コンテキストに従って他の値を対応する値に置き換えることができる.ここで、プレースホルダはコンテキスト配列のキー名と一致する必要があります.プレースホルダの名前は、左カッコ{と右カッコ}で含める必要があります.ただし、カッコと名前の間には必ずスペース文字は使用できません.プレースホルダの名前は、A-Z、a-z、0-9、下線_、および英語の句点.のみから構成され、他の文字は将来のプレースホルダ仕様の保持として使用されるべきである.インプリメンテーションは、プレースホルダに対して異なるエスケープおよび変換ポリシーを採用することによって、最終的なログを生成することができる.使用者はコンテキストを知らない前提で、事前にプレースホルダをエスケープすべきではない.次に、プレースホルダの使用例を示します.

/**
 *                  
 */
function interpolate($message, array $context = array())
{
    //                  
    $replace = array();
    foreach ($context as $key => $val) {
        $replace['{' . $key . '}'] = $val;
    }

    //            ，            。
    return strtr($message, $replace);
}

//               。
$message = "User {username} created";

//             ，        ，      。
$context = array('username' => 'bolivar');

//    "Username bolivar created"
echo interpolate($message, $context);

1.3コンテキスト

各レコード関数は、文字列タイプでは表現できない情報をロードするためのコンテキスト配列パラメータを受け入れます.それはいかなる情報をロードすることができるので、実装者は、ロードされた情報を正しく処理することができ、ロードされたデータに対して異常を投げ出したり、PHPエラー、警告、または注意情報(error、warning、notice)を生成したりしてはならない.

コンテキストパラメータを介してExceptionオブジェクトに渡す必要がある場合は、exceptionをキー名としなければならない.異常情報の記録は一般的であるため,記録クラスライブラリの下層で実現できれば,実現者に異常情報から繭を剥がすことができる.もちろん、実装者は、それを使用する際に、exceptionというキー名のキー値が本当にExceptionであるかどうかを確認しなければならない.結局、それは任意の情報をロードすることができる.

1.4アシスタントクラスとインタフェース

Psr\Log\AbstractLoggerクラスは、logメソッドを継承して実装するだけで、LoggerInterfaceインタフェースを容易に実現することができ、他の8つのメソッドは、記録情報とコンテキスト情報を伝達することができる.

も同様に、Psr\Log\LoggerTraitを使用しても、そのうちのlogの方法を実装するだけでよい.しかしながら、traits多重化可能なコードブロックがインタフェースを実装できない前に、implement LoggerInterfaceが必要であることに特に注意されたい.

使用可能なログレコーダがない場合、Psr\Log\NullLoggerインタフェースは、使用者に代替のログ「ブラックホール」を提供することができる.しかし、コンテキストの構築がリソースを非常に消費する場合、条件付きチェックのログ記録はより良い方法かもしれません.

Psr\Log\LoggerAwareInterfaceインタフェースは、1つのsetLogger(LoggerInterface $logger)メソッドのみを含み、フレームワークは、任意のログ記録インスタンスを自動的に接続するために使用することができる.

Psr\Log\LoggerAwareTrait trait多重化可能なコードブロックは、任意のクラスで使用することができ、それによって提供される$this->loggerだけで、同等のインタフェースを簡単に実現することができる.

Psr\Log\LogLevelクラスには8つの記録レベル定数が搭載されている.

2.パッケージ
上記のインタフェース、クラス、および関連する異常クラス、およびpsr/logファイルパッケージに含まれる一連の実装検出ファイル.
3. Psr\Log\LoggerInterface

4. Psr\Log\LoggerAwareInterface

5. Psr\Log\LogLevel