README

Slim, simple and full compatible PSR-3 Logger library for PHP.

Installation

Install via the composer utility.

composer require "phoole/logger"

or add the following lines to your composer.json

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

Usage

Create the logger instance with a channel 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());

Concepts

• Log entry

  A log entry is a message in the form of an object. It solves the problem of 'WHAT TO BE SENT OUT'. It has a message template, and some processors to process its context.

  For example, Entry\MemoryInfo is a predefined log entry with a message template of {memory_used}M memory used , peak usage is {memory_peak}M and one Processor\MemoryProcessor processor.

  // 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 is the log entry prototype used whenever text message is to be logged

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

  To define your own log entry,

  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']);

• Processor

  Processors are associated with log entry classes. They solve the problem of 'WHAT EXTRA INFO TO SENT OUT'. They will inject information into entries' context. Processors are 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;
      }
  } 

  Processors are attached to log entries either in the entry class definition as follows,

  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(),
          ];
      }
  }

  or during the handler attachment

  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(),
          ...
      )
  );

• Handler

  Handlers solve the problem of 'WHERE TO SEND MESSAGE'. They take a log entry object and send it to somewhere.

  Handlers takes the form of callable(LogEntryInterface $entry) as follows,

  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);
      }
  }

  Handlers are added to the $logger with specific log level and type of log message they are going to handle (default is LogEntryInterface).

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

• Formatter

  Formatters solve the problem of 'HOW MESSAGE WILL BE PRESENTED''. Each handler of the type Handler\HandlerAbstract may have formatter specified during its initiation.

  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 related

  See PSR-3 for standard related APIs.

• Phoole\Logger\Logger related

  • __construct(string $channel)

    Create the logger with a channel id.

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

    Add one handler to specified channel with the priority.

• Phoole\Logger\Entry\LogEntry related

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

    This method will returns called class name.

Testing

$ composer test

Dependencies

• PHP >= 7.2.0

• phoole/base 1.*

License

• Apache 2.0