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

phoole / logger

Maintainers

Details