PSR-3 日志接口规范

本文描述了日志类库的通用接口规范。

主要目标是让类库获得一个 Psr\Log\LoggerInterface对象并且通过简单和通用的方式来写日志。有自定义需求的框架和CMS系统,可以根据情况扩展这个接口,但是应该和本文档保持兼容。这能确保使用第三方类库文件时仍能写到集中的应用程序日志中。

关键词 “必须”(“MUST”)、“一定不可/一定不能”(“MUST NOT”)、“需要”(“REQUIRED”)、

“将会”(“SHALL”)、“不会”(“SHALL NOT”)、“应该”(“SHOULD”)、“不该”(“SHOULD NOT”)、

“推荐”(“RECOMMENDED”)、“可以”(“MAY”)和”可选“(“OPTIONAL”)的详细描述可参见 RFC 2119

单词implementor(实现者)在这个文档中被解释为:在日志相关的库或框架实现LoggerInterface接口的人。用这些实现者开发出来的类库的人都被称作user(用户)

1. 规范

1.1 基础

  • LoggerInterface接口对外定义了八个方法,分别用来记录RFC 5424中定义的八个等级的日志:debug、 info、 notice、 warning、 error、 critical、 alert 以及 emergency 。
  • 第九个方法log,其第一个参数为记录的等级。用一个日志等级常量来调用这个方法必须和直接调用指定等级方法的结果一致。如果传入的等级常量参数没有预先定义,则必须抛出Psr\Log\InvalidArgumentException类型的异常。在不确定的情况下,使用者不应该使用自定义的日志等级。

1.2 信息

  • 每个方法都接受一个字符串类型或者是有__toString()方法的对象作为记录信息参数。实现者可以对传入的对象有特殊的处理。如果不是这样,实现者必须把它转换成字符串。
  • message参数中可能包含一些可以被上下文数组所替换的占位符。

其中占位符必须与上下文数组中的键名保持一致。

占位符名字必须使用一对花括号来作为分隔符。在占位符和分隔符之间一定不能有任何空格。

占位符的名称应该只由A-Za-z,0-9、下划线_、以及英文的句号.组成,其它的字符作为以后占位符规范的保留字。

实现者可以通过对占位符采用不同的转义和转换策略,来生成最终的日志。而用户在不知道上下文的前提下,不应该提前转义占位符。

下面提供一个占位符替换的例子,仅作为参考:

 /**
   * Interpolates context values into the message placeholders.
   */
  function interpolate($message, array $context = array())
  {
      // build a replacement array with braces around the context keys
      $replace = array();
      foreach ($context as $key => $val) {
          // check that the value can be casted to string
          if (!is_array($val) && (!is_object($val) || method_exists($val, ‘__toString‘))) {
              $replace[‘{‘ . $key . ‘}‘] = $val;
          }
      }

      // interpolate replacement values into the message and return
      return strtr($message, $replace);
  }

  // a message with brace-delimited placeholder names
  $message = "User {username} created";

  // a context array of placeholder names => replacement values
  $context = array(‘username‘ => ‘bolivar‘);

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

1.3 上下文

  • 每个记录函数都接受一个上下文数组参数,用来存储不适合在字符串中填充的信息。它可以装载任何信息,所以实现者必须确保能正确处理其装载的信息,对于其装载的数据,一定不能抛出异常,或产生PHP出错、警告或提醒信息(error、warning、notice)。
  • 如果在上下文参数中传入了一个异常对象,它必须exception作为键名。记录异常信息是一种常见的模式,并且可以在日志系统支持的情况下从异常中提取出整个调用栈。实现者在使用它时,必须确保键名为 ‘exception‘的键值是否真的是一个Exception,毕竟它可以装载任何信息。

1.4 助手类和接口

  • Psr\Log\AbstractLogger类让你通过继承它并实现通用的log方法来方便的实现LoggerInterface接口。而其他八个方法将会把消息和上下文转发给log方法。
  • 同样地,使用Psr\Log\LoggerTrait也只需实现其中的log方法。不过,需要特别注意的是,在traits可复用代码块还不能实现接口前,还需要implement LoggerInterface
  • Psr\Log\NullLogger是和接口一起提供的。它在没有可用的日志记录器时,可以为使用日志接口的用户们提供一个后备的“黑洞”。然而,当上下文的构建非常消耗资源时,带条件检查的日志记录或许是更好的办法。
  • Psr\Log\LoggerAwareInterface只有一个setLogger(LoggerInterface $logger)方法,它可以在框架中用来随意设置一个日志记录器。
  • Psr\Log\LoggerAwareTraittrait可复用代码块可以在任何的类里面使用,只需通过它提供的$this->logger,就可以轻松地实现等同的接口。
  • Psr\Log\LogLevel 类装载了八个记录等级常量。

2. 包

psr/log中提供了上文描述过的接口和类,以及相关的异常类,还有一组用来验证你的实现的单元测试。

3. Psr\Log\LoggerInterface

<?php

namespace Psr\Log;

/**
 * Describes a logger instance
 *
 * The message MUST be a string or object implementing __toString().
 *
 * The message MAY contain placeholders in the form: {foo} where foo
 * will be replaced by the context data in key "foo".
 *
 * The context array can contain arbitrary data, the only assumption that
 * can be made by implementors is that if an Exception instance is given
 * to produce a stack trace, it MUST be in a key named "exception".
 *
 * See https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md
 * for the full interface specification.
 */
interface LoggerInterface
{
    /**
     * System is unusable.
     *
     * @param string $message
     * @param array $context
     * @return null
     */
    public function emergency($message, array $context = array());

    /**
     * Action must be taken immediately.
     *
     * Example: Entire website down, database unavailable, etc. This should
     * trigger the SMS alerts and wake you up.
     *
     * @param string $message
     * @param array $context
     * @return null
     */
    public function alert($message, array $context = array());

    /**
     * Critical conditions.
     *
     * Example: Application component unavailable, unexpected exception.
     *
     * @param string $message
     * @param array $context
     * @return null
     */
    public function critical($message, array $context = array());

    /**
     * Runtime errors that do not require immediate action but should typically
     * be logged and monitored.
     *
     * @param string $message
     * @param array $context
     * @return null
     */
    public function error($message, array $context = array());

    /**
     * Exceptional occurrences that are not errors.
     *
     * Example: Use of deprecated APIs, poor use of an API, undesirable things
     * that are not necessarily wrong.
     *
     * @param string $message
     * @param array $context
     * @return null
     */
    public function warning($message, array $context = array());

    /**
     * Normal but significant events.
     *
     * @param string $message
     * @param array $context
     * @return null
     */
    public function notice($message, array $context = array());

    /**
     * Interesting events.
     *
     * Example: User logs in, SQL logs.
     *
     * @param string $message
     * @param array $context
     * @return null
     */
    public function info($message, array $context = array());

    /**
     * Detailed debug information.
     *
     * @param string $message
     * @param array $context
     * @return null
     */
    public function debug($message, array $context = array());

    /**
     * Logs with an arbitrary level.
     *
     * @param mixed $level
     * @param string $message
     * @param array $context
     * @return null
     */
    public function log($level, $message, array $context = array());
}

4. Psr\Log\LoggerAwareInterface

<?php

namespace Psr\Log;

/**
 * Describes a logger-aware instance
 */
interface LoggerAwareInterface
{
    /**
     * Sets a logger instance on the object
     *
     * @param LoggerInterface $logger
     * @return null
     */
    public function setLogger(LoggerInterface $logger);
}

5. Psr\Log\LogLevel

<?php

namespace Psr\Log;

/**
 * Describes log levels
 */
class LogLevel
{
    const EMERGENCY = ‘emergency‘;
    const ALERT     = ‘alert‘;
    const CRITICAL  = ‘critical‘;
    const ERROR     = ‘error‘;
    const WARNING   = ‘warning‘;
    const NOTICE    = ‘notice‘;
    const INFO      = ‘info‘;
    const DEBUG     = ‘debug‘;
}
时间: 2024-09-30 14:52:23

PSR-3 日志接口规范的相关文章

PSR规范

目前包括以下几个规范: PSR-0(弃用) PSR-1 PSR-2 PSR-3 PSR-4 1.PSR-0 自动加载规范,此规范已被启用-本规范已于2014年10月21日被标记为弃用,目前新的替代规范为[PSR-4] 本文是为自动加载器实现通用自动加载所需要遵循的编码规范 一个标准的命名空间与类名称的定义必须符合以下结构:\<Vendor Name><Namespace>*(ClassName) 其中Vendor Name 为每个命名空间都必须要有的一个顶级命名空间名 需要的话,每

PHP PSR基本代码规范(中文版)

PSR-1 基本代码规范 本篇规范制定了代码基本元素的相关标准,以确保共享的PHP代码间具有较高程度的技术互通性. 关键词 "必须"("MUST")."一定不可/一定不能"("MUST NOT")."需要"("REQUIRED")."将会"("SHALL")."不会"("SHALL NOT")."应

psr规范发展历程

====================PSR-0(自动加载规范)======================= PSR-0(Autoloading Standard)类自动加载规范,该规范现已废弃(Deprecated),它将由PSR-4替代. 1.一个完全合格的命名空间和类名必须遵循以下结构 "\VendorName\Namespace\ClassName" 2.每个命名空间必须有顶级的命名空间 "VendorName" 3.每个命名空间可以有任意多个子命名空间

Psr(psr1+psr2+psr3)

转自:https://blog.csdn.net/ax1232/article/details/75667187 1. 概览 PHP代码文件必须以 <?php 或 <?= 标签开始:    PHP代码文件必须以 不带BOM的 UTF-8 编码:    PHP代码中应该只定义类.函数.常量等声明,或其他会产生 从属效应 的操作(如:生成文件输出以及修改.ini配置文件等),二者只能选其一:    命名空间以及类必须符合 PSR 的自动加载规范: PSR-4 :    类的命名必须遵循 Studl

PHP日志扩展 SeasLog-1.6.8, 性能更优

SeasLog-1.6.8 发布了,性能更优. 改进日志: 1.6.8: 优化内存使用和性能,修复已知Bug. - Fixed issue #97 PHP5.* Cached Block. - Fixed issue #98 SeasLog::analyzerDetail(NULL). - Fixed issue #100 #102 #103 memory leak. - Fixed Dir chmod 0755 and File chmod 0666. 1.6.0:此次改进支持appender

PHP PSR规范

PHP PSR-1 基本代码规范(中文版)  http://segmentfault.com/a/1190000002521577PHP PSR-2 代码风格规范 (中文版)  http://segmentfault.com/a/1190000002521620PHP PSR-3 日志接口规范 (中文版)  http://segmentfault.com/a/1190000002521644PHP PSR-4 Autoloader 自动加载(中文版) http://segmentfault.co

使用SeasLog打造PHP项目中的高性能日志组件(一)

云智慧(北京)科技有限公司 高驰涛 什么是SeasLog SeasLog是一个C语言编写的PHP扩展,提供一组规范标准的功能函数,在PHP项目中方便.规范.高效地写日志,以及快速地读取和查询日志. 为什么使用SeasLog 无论在什么应用中,log日志都是架构中不可缺少的一个重要组成部分,它通常是系统或软件.应用的运行记录.通过log的分析,可以方便用户了解系统或软件.应用的运行情况:如果你的应用log足够丰富,也可以分析以往用户的操作行为.类型喜好.地域分布或其他更多信息:如果一个应用的log

【PHP开发规范】老生常谈的编码开发规范你懂多少?

[PHP开发规范]老生常谈的编码开发规范你懂多少? 这几天看了一下阿里技术发布的一套Java开发规范<阿里巴巴Java开发手册>,里面写了阿里内部的Java开发规范标准,写的很好.这套Java统一规范标准将有助于提高行业编码规范化水平,帮助行业人员提高开发质量和效率.大大降低代码维护成本. 看完我去搜下了一些PHP的一些开发规范标准,其中了解到了PSR规范是PHP行业中常用的一套开发标准.感叹自己学得那么少,标准的规范这么晚才发现. 其实对于新手或者有几年经验的开发者来说,这些规范我们都要掌握

PHP 的一些开发规范

长篇慎入 分以下几点说明 一些编码的经验 PSR-1 PSR-2 PSR-3 PSR-4 一些编码的经验 变量命名 不用拼音 驼峰或下划线风格要一致 单词要有意义 不用关键字 常量全大写用下划线连接 代码注释 尽量让代码可读性提高,减少代码上的注释 函数头部可以描述参数和返回值及功能的注释 算法类代码一定要加注释说明 代码备份 使用 github, 本地留一份 编码统一 PHP编码 == HTML编码 == 数据库编码 == UTF-8 header("Content-type: text/ht