README

PHP 的精简、简单且完全兼容 PSR-3 日志库。

安装

使用 composer 工具安装。

composer require "phoole/logger"

或者将以下行添加到您的 composer.json

{
    "require": {
       "phoole/logger": "1.*"
    }
}

用法

使用频道 ID 创建日志实例，

use Psr\Log\LogLevel;
use Phoole\Logger\Logger;
use Phoole\Logger\Entry\MemoryInfo;
use Phoole\Logger\Handler\SyslogHandler;
use Phoole\Logger\Handler\TerminalHandler;

// with channel id
$logger = new Logger('MyApp');

// log every warning to syslog
$logger->addHandler(
    LogLevel::WARNING,
    new SyslogHandler()
);

// log to terminal for MemoryInfo entry
$logger->addHandler(
    LogLevel::INFO,
    new TerminalHandler(),
    MemoryInfo::class // handle this log object only
);

// log a text message
$logger->warning('a warning message');

// log memory usage
$logger->info(new MemoryInfo());

概念

• 日志条目

  日志条目 是一种对象形式的消息。它解决了 “发送什么” 的问题。它有一个消息模板和一些处理器来处理其上下文。

  例如，Entry\MemoryInfo 是一个预定义的日志条目，具有消息模板 {memory_used}M 内存使用，峰值使用是 {memory_peak}M 和一个 Processor\MemoryProcessor 处理器。

  // with predefined template and processor
  $logger->warning(new MemoryInfo());
  
  // use new template
  $logger->warning(new MemoryInfo('Peak memory usage is {memory_peak}M'));

  Entry\LogEntry 是在需要记录文本消息时使用的日志条目原型

  // using LogEntry
  $logger->info('test only');

  要定义自己的日志条目，

  use Phoole\Logger\Entry\LogEntry;
  
  class MyMessage extends LogEntry
  {
      // message template
      protected $message = 'your {template}';
  }
  
  // add handler
  $logger->addHandler(
      'warning', // level
      function(LogEntry $entry) { // a handler
          echo (string) $entry;
      },
      MyMessage::class // handle this type of message only
  );
  
  // output: 'your wow'
  $logger->error(new MyMessage(), ['template' => 'wow']);

• 处理器

  处理器 与日志条目类相关联。它们解决了 “发送什么额外信息” 的问题。它们会将信息注入到条目的上下文中。处理器是 callable(LogEntryInterface $entry)，

  use Phoole\Logger\Processor\ProcessorAbstract;
  
  // closure
  $processor1 = function(LogEntry $entry) {
  };
  
  // invokable object
  $processor2 = new class() {
      public function __invoke(LogEntry $entry)
      {
      }
  }
  
  // extends
  class Processor3 extends ProcessorAbstract
  {
      protected function updateContext(array $context): array
      {
          $context['bingo'] = 'wow';
          return $context;
      }
  } 

  处理器可以通过以下方式附加到日志条目中，

  class MyMessage extends LogEntry
  {
      // message template
      protected $message = 'your {template}';
        
      // define processors for this class
      protected static function classProcessors(): array
      {
          return [
              function(LogEntry $entry) {
                  $context = $entry->getContext();
                  $context['template'] = 'wow';
                  $entry->setContext($context);
              },
              new myProcessor(),
          ];
      }
  }

  或者在进行处理器附加时

  use Phoole\Logger\Handler\SyslogHandler;
  
  // will also add 'Processor1' and 'Processor2' to 'MyMessage' class
  $logger->addHandler(
      'info',
      new SyslogHandler(),
      MyMessage::addProcessor(
          new Processor1(),
          new Processor2(),
          ...
      )
  );

• 处理器

  处理器 解决了 “消息发送到哪里” 的问题。它们接收一个日志条目对象并将其发送到某个地方。

  处理器采用以下形式的 callable(LogEntryInterface $entry)，

  use Phoole\Logger\Handler\HandlerAbstract;
  
  $handler1 = function(LogEntry $entry) {
      echo (string) $entry;
  }
  
  $handler2 = new class() {
      public function __invoke(LogEntry $entry)
      {
      }
  }
  
  class Handler3 extends HandlerAbstract
  {
      protected function write(LogEntryInterface $entry)
      {
          echo $this->>getFormatter()->format($entry);
      }
  }

  处理器被添加到 $logger 中，具有特定的日志级别和将要处理的日志消息类型（默认为 LogEntryInterface）。

  $logger->addHandler(
      LogLevel::WARNING,
      new TerminalHandler(),
      LogEntryInterface::class // this is the default anyway
  );

• 格式化器

  格式化器 解决了 “消息如何呈现” 的问题。每个类型为 Handler\HandlerAbstract 的处理器在其初始化期间可能指定了格式化器。

  use Phoole\Logger\Handler\TerminalHandler;
  use Phoole\Logger\Formatter\AnsiFormatter;
  
  // use ANSI Color formatter
  $handler = new TerminalHandler(new AnsiFormatter());
  
  // add handler handles 'ConsoleMessage' ONLY
  $logger->addHandler('debug', $handler, ConsoleMessage::class);
  
  // log to console
  $logger->info(new ConsoleMessage('exited with error.'));
  
  // this will goes handlers handling 'LogEntry'
  $logger->info('exited with error');

APIs

• LoggerInterface 相关

  有关相关 API 的信息，请参阅 PSR-3。

• Phoole\Logger\Logger 相关

  • __construct(string $channel)

    使用频道 ID 创建日志。

  • addHandler(string $level, callable $handler, string $entryClass, int $priority = 50): $this

    以优先级添加一个处理器到指定的频道。

• Phoole\Logger\Entry\LogEntry 相关

  • static function addProcessor(callable ...$callables): string

    此方法将返回调用的类名。

测试

$ composer test

依赖关系

• PHP >= 7.2.0

• phoole/base 1.*

许可证

• Apache 2.0