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

ログインターフェース仕様

この記事は、ログ ライブラリの一般的なインターフェイス仕様を定式化します。

この仕様の主な目的は、ログ ライブラリが PsrLogLoggerInterface オブジェクトを受け取ることによって、シンプルかつ汎用的な方法でログ情報を記録できるようにすることです。

必要に応じて、フレームワークと CMS コンテンツ管理システムはこのインターフェースを拡張できますが、
この仕様に従う必要があります。これにより、サードパーティのクラス ライブラリ ファイルを使用する場合でもログ インターフェースを正常に接続できるようになります。 キーワード「しなければならない」（「MUST」）、「してはならない/してはならない」（「MUST NOT」）、「必要」（「必須」）、
「するつもり」（「SHALL」）、「しない」（ 「してはならない」)、「すべきである」(「すべきである」)、「すべきではない」(「すべきではない」)、

「推奨する」(「推奨」)、「できる」(「してもよい」)、および「オプション」(" OPTIONAL") については、[RFC 2119][] で詳細に説明されています。

この記事の実装者は、LoggerInterface インターフェイスを実装するクラス ライブラリまたはフレームワークを指します。つまり、LoggerInterface のユーザーです。

仕様

1.1 基本仕様 LoggerInterface インターフェースは 8 つの外部メソッドを定義しており、[RFC 5424][] で定義されている 8 つのレベルのログ (デバッグ、情報、通知、警告、エラー、クリティカル、アラート、緊急) を記録するために使用されます。

9 番目のメソッド - log、その最初のパラメータはレコードのレベルです。このメソッドは、事前定義されたレベル定数をパラメータとして使用して呼び出すことができ、上記の 8 つのメソッドを直接呼び出すのと同じ効果が得られます。受信レベル定数パラメーターが事前定義されていない場合は、PsrLogInvalidArgumentException タイプの例外をスローする必要があります。ユーザーは、不確実な状況下でサポートされていないレベル定数を使用してこのメ​​ソッドを呼び出すべきではありません

---

。

1.2 レコード情報

上記の各メソッドは、文字列型または __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);

}

// 置換情報を含むコンテキスト配列。キー名はプレースホルダー名、キー値は置換値です。
$context = array('username' => 'bolivar');

// "ユーザー名 bolivar が作成されました" を出力
echo interpolate($message, $context);


コードをコピー

1.3 コンテキスト

各記録関数は、文字列型では表現できない情報をロードするためにコンテキスト配列パラメーターを受け入れます。  あらゆる情報をロードできるため、実装者は  ロードする情報を正しく処理できることを確認する必要があり、 例外をスローしたり、PHP エラー、警告、リマインダー メッセージ (エラー、警告、注意）。 
Exception オブジェクトがコンテキスト パラメータを通じて渡される場合、 キー名として「例外」を使用する必要があります。 例外情報のログ記録は非常に一般的であるため、ログ記録クラス ライブラリの最後に実装できれば、実装者は例外情報を削除できます。 もちろん、これを使用する場合、実装者は、キー名「例外」を持つキー値が本当に例外であるかどうかを  確認する必要があります。結局のところ、あらゆる情報を  読み込むことができます。 

1.4 ヘルパークラスとインターフェース

PsrLogAbstractLogger クラスを使用すると、LoggerInterface インターフェイスを継承して log メソッドを実装するだけで簡単に実装できます。他の 8 つのメソッドはログ情報とコンテキスト情報をそれに渡すことができます。 
同様に、PsrLogLoggerTrait を使用するには、log メソッドを実装するだけです。ただし、特性の再利用可能なコード ブロックがインターフェイスを実装できる前に、LoggerInterface を実装する必要があることに注意することが重要です。 
利用可能なロガーがない場合、PsrLogNullLogger インターフェイスは、ユーザーにバックアップ ログ「ブラック ホール」を提供できます。ただし、コンテキストの構築がリソースを非常に大量に消費する場合は、条件付きチェックを使用してログを記録する方が良い方法である可能性があります。 
PsrLogLoggerAwareInterface インターフェイスには setLogger(LoggerInterface $logger) メソッドのみが含まれており、フレームワークはこれを使用して任意のログ インスタンスに自動的に接続できます。 
 PsrLogLoggerAwareTrait 特性の再利用可能なコード ブロックは、どのクラスでも使用でき、同等のインターフェイスは、それが提供する $this->logger を通じて簡単に実装できます。 
PsrLogLogLevel クラスは 8 つのログ レベル定数を読み込みます。 

バッグ

上記のインターフェイス、クラス、および関連する例外クラス、および一連の実装検出ファイルは、psr/log ファイル パッケージに含まれています。 
PsrLogLoggerInterface



namespace PsrLog;

/**
 * ログインスタンス
 *
 * ログ情報変数 - メッセージ、**必須** 文字列または __toString() メソッドを実装するオブジェクトです。
 *
 * ログ情報変数 **can** には、"{foo}" (foo を表す) 形式のプレースホルダーを含めることができます。
 * これは、コンテキスト配列内のキー値 "foo" に置き換えられます。
 *
 * コンテキスト配列は任意のデータを保持できます。唯一の制限は、例外オブジェクトを保持する場合、そのキー名は「例外」でなければならないことです。
 *
 * 詳細については、https://github.com/PizzaLiu/PHP-FIG/blob/master/PSR-3-logger-interface-cn.mdを参照してください
*/
interface LoggerInterface
{
 /**
 * システムが利用できません
 *
 * @param string $message
 * @param array $context
 * @return null
*/
 public functionEmergency($message, array $context = array());

 /**
 * **すぐに行動を起こす必要があります**
 *
 * たとえば、Web サイト全体がダウンしている場合、データベースが利用できない場合、またはその他の状況の場合は、ユーザーを目覚めさせるために警告テキスト メッセージが送信される必要があります。
 *
 * @param string $message
 * @param array $context
 * @return null
*/
 public functionalert($message, array $context = array());

 /**
 * 緊急
 *
 * 例: プログラム コンポーネントが利用できない、または予期しない例外が発生します。
 *
 * @param string $message
 * @param array $context
 * @return null
*/
 public functioncritical($message, array $context = array());

 /**
 * 実行時に発生したエラーは直ちに対処する必要はありませんが、検出のために記録する必要があります。
 *
 * @param string $message
 * @param array $context
 * @return null
*/
 public function error($message, array $context = array());

 /**
 * エラー以外の例外が発生しました。
 *
 * 例: 非推奨の API の使用、API の誤った使用、または予期しない不要なエラーの原因。
 *
 * @param string $message
 * @param array $context
 * @return null
*/
 public function warning ($message, array $context = array());

 /**
 *一般的に重要なイベント。
 *
 * @param string $message
 * @param array $context
 * @return null
*/
 public function Notice($message, array $context = array());

 /**
 * 重要なイベント
 *
 * 例: ユーザー ログインと SQL レコード。
 *
 * @param string $message
 * @param array $context
 * @return null
*/
 パブリック関数 info($message, array $context = array());

 /**
 * デバッグの詳細
 *
 * @param string $message
 * @param array $context
 * @return null
*/
 public function debug($message, array $context = array());

 /**
 * 任意のレベルでのロギング
 *
 * @parammixed $level
 * @param string $message
 * @param array $context
 * @return null
*/
 public function log($level, $message, array $context = array());
}
PsrLogLoggerAwareInterface



namespace PsrLog;

/**
 * ロガー対応定義インスタンス
*/
interface LoggerAwareInterface
{
 /**
 * ロギングインスタンスをセットアップします
 *
 * @param LoggerInterface $logger
 * @return null
*/
 public function setLogger(LoggerInterface $logger);
}
PsrLogLogLevel



namespace PsrLog;

/**
 * ログレベル定数の定義
*/
class LogLevel
{
 const EMERGENCY = '緊急';
 const ALERT = 'alert';
 const CRITICAL = ' Critical';
 const ERROR = 'error';
 const WARNING = 'warning';
 const NOTICE = 'notice';
 const INFO = 'info';
 const DEBUG = 'debug';
}
转自Github(PizzaLiu)

PHP、PSR