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