README

PLEASE USE phoole/logger library instead

phossa2/logger is a PSR-3 compliant logging library. It is a rewrite of Monolog with couple of changes.

It requires PHP 5.4, supports PHP 7.0+ and HHVM. It is compliant with PSR-1, PSR-2, PSR-3, PSR-4, and the proposed PSR-5.

Installation

Install via the composer utility.

composer require "phossa2/logger=2.*"

or add the following lines to your composer.json

{
    "require": {
       "phossa2/logger": "2.*"
    }
}

Usage

Create the logger instance with default channel,

use Phossa2\Logger\Logger;
use Phossa2\Logger\Handler\SyslogHandler;
use Phossa2\Logger\Handler\LogfileHandler;
use Phossa2\Logger\Processor\MemoryProcessor;
use Phossa2\Logger\Processor\InterpolateProcessor;

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

// attach memory processor
$logger->addProcessor(new MemoryProcessor());

// attach interpolate processor to all channels' ('*') end (-100)
$logger->addProcessor(new InterpolateProcessor(), '*', -100);

// attach syslog handler to user related channels
$logger->addHandler('debug', new SyslogHandler(), 'user.*');

// attach file handler to all channels
$logger->addHandler('warning', new LogfileHandler('/tmp/app.log'));

// log to system.usage channel
$logger
    ->with('system.usage')
    ->debug('memory used {memory.used} and peak is {memory.peak}');

// log to user.login channel
$logger
    ->with('user.login')
    ->info('user logged in as {user.username}', ['user' => $user]);

// log to default channel
$logger->debug('a test message');

Features

Channels

Creative usage of channels. Handler and Processor now can be bound to different channels, also with channel name globbing.
- Channel globbing
  
  By default, handlers and processors are bound to '*' channel which globs to all. But they also can be bound to channels like 'user.*' or more specific one 'user.login'.
```
// bind to 'user.*' channels
$logger->addHandler('warning', new LogfileHandler('/log/user.log'), 'user.*');

// bind to 'system.*' channels
$logger->addHandler('error', new LogfileHandler('/log/system.log'), 'system.*');

// add user info only in 'user.*' channel
$logger->addProcessor(new UserProcessor(), 'user.*');
```
  log messages can be sent to specific channels by using of with() in front of any logging related methods, such as log(), warning() etc.
```
$logger->with('user.login')->info('user {user.username} logged info');
```
  The info() method in the previous code will trigger user info being inserted into context array by the UserProcessor and being logged to file /log/user.log.
  
  Note: Channel names are case insensitive.
  
  Note: Same handler or processor can be bound to different channels. But will be executed only ONCE in one log call.
- Single logger
  
  With the support for logging to different channels, there is no need to create multiple loggers in one application. By carefully designing your channel hierachy, you may use one logger through out your site.

Priority

Handlers and processors are now can injected into the logger with different priorities (range from -100 to 100, default is 0).

Higher priority means executed first

// add user info at first
$logger->addProcessor(new UserProcessor(), 'user.*', 100);

// interpolate should be done last (just before executing handlers)
$logger->addProcessor(new InterpolateProcessor(), '*', -100);

First in first out(executed) for same priority

Default priority value is 0. The following handlers executed in the order of their addition.

// log to file first
$logger->addHandler('debug', new LogfileHandler('/log/log.txt'));

// then log to mail
$logger->addHandler('debug', new MailHandler('admin@my.com'));

Simple callable interface

Handlers, formatters, processors are now all using the single interface

public function __invoke(LogEntryInterface $logEntry);

Which means, user may use predefined functions or other callables to servce as handler, formatter or processor, as long as these callables take the LogEntryInterface as the parameter.

A quick handler as follows,

function myHandler(LogEntryInterface $logEntry) {
    // get formatted message
    $formatted = $logEntry->getFormatted();

    // write to my device ...
}

Or even,

$logger->addHandler('error', function($log) {
    // write the log to my device
}, 'user.*');

LogEntry

In stead of using array as data type for the log message. The LogEntryInterface is defined to serve as default data type for logs.

You may even extend the LogEntry class, and use it in your logger
```
class MyLogEntry extends LogEntry
{
    // ...
}
```
Use it in your logger as the prototype for all log messages,
```
$entryPrototype = new MyLogEntry('channel','debug', 'message');

$logger = new Logger('MyApp', $entryPrototype);
```

APIs

LoggerInterface related

See PSR-3 for standard related APIs.
Phossa2\Logger\Logger related
- __construct(string $defaultChannel = 'LOGGER', LogEntryInterface $logPrototype = null)
  
  Create the logger.
- with(string $channel): $this
  
  Specify the channel for the comming logging method.
- addHandler(string $level, callable $handler, string $channel = '*', int $priority = 0): $this
  
  Add one handler to specified channel with the priority.
- addProcessor(callable $processor, string $channel = '*', int $priority = 0): $this
  
  Add one processor to specified channel with the priority.
- removeHandler(callable|string $handlerOrClassname, $channel = '')
  
  Remove the handler (or specify handler's classname) from the specified channel. If $channel is empty, then remove from all channels.
- removeProcessor(callable|string $processorOrClassname, $channel = '')
  
  Remove the processor (or specify processor's classname) from the specified channel. If $channel is empty, then remove from all channels.

Change log

Please see CHANGELOG from more information.

Testing

$ composer test

Contributing

Please see CONTRIBUTE for more information.

Dependencies

PHP >= 5.4.0
phossa2/shared >= 2.0.21

License

MIT License

phossa2 / logger

Maintainers

Details