apix/log

Minimalist, thin and fast PSR-3 compliant (multi-bucket) logger.

1.2.1 2016-09-22 10:51 UTC

README

Latest Stable Version Build Status Code Quality Code Coverage License

Minimalist and fast PSR-3 compliant logger.

  • Light, come out-of-the-box bundle with wrappers for:
    • ErrorLog, File, Mail, Sapi ~ built around the error_log() function,
    • Runtime ~ as an Array/ArrayObject wrapper, and Nil ~ as Null wrapper,
    • Stream ~ logs are sent to sockets, local and remote files, filters and other similar resources (default to standard output bypassing output buffering).
  • Extendable, additional logging backends are available:
  • Clean API, see the LoggerInterface and the LogFormatterInterface.
  • 100% Unit tested and compliant with PSR0, PSR1 and PSR2.
  • Continuously integrated against PHP 5.3, 5.4, 5.5, 5.6, 7.0 and HHVM.
  • Available as a Composer and as a PEAR package.

Feel free to comment, send pull requests and patches...

🆕Log dispatch can be postponed/accumulated using setDeferred().

Basic usage ~ standalone

use Apix\Log;

$urgent_logger = new Logger\Mail('franck@foo.bar');
$urgent_logger->setMinLevel('critical');   // catch logs >= to `critical`

This simple logger is now set to intercept critical, alert and emergency logs.

To log an event, use:

$urgent_logger->alert('Running out of {stuff}', ['stuff' => 'beers']);

Advanced usage ~ multi-logs dispatcher

Lets create an additional logger with purpose of catching log entries that have a severity level of warning or more -- see the log levels for the order.

$app_logger = new Logger\File('/var/log/apix_app.log');
$app_logger->setMinLevel('warning')  // intercept logs that are >= `warning`
           ->setCascading(false)     // don't propagate to further buckets
           ->setDeferred(true);      // postpone/accumulate logs processing

setCascading() was set to false (default is true) so the entries caught here won't continue downstream past that particular log bucket. setDeferred() was set to true (default is false) so processing happen on __destruct (end of script generally) rather than on the fly.

Now, lets create a main logger object and inject the two previous loggers.

// The main logger object (injecting an array of loggers)
$logger = new Logger( array($urgent_logger, $app_logger) );

Lets create an additional logger -- just for development/debug purposes.

if(DEBUG) {
  // Bucket for the remaining logs -- i.e. `notice`, `info` and `debug`
  $dev_logger = new Logger\Stream(); // default to screen without output buffer  
  // $dev_logger = new Logger\File('/tmp/apix_debug.log'); 
  $dev_logger->setMinLevel('debug');

  $logger->add($dev_logger);   		// another way to inject a log bucket
}

Finally, lets push some log entries:

$e = new \Exception('Boo!');

// handled by both $urgent_logger & $app_logger
$logger->critical('OMG saw {bad-exception}', [ 'bad-exception' => $e ]);

// handled by $app_logger
$logger->error($e); // push an object (or array) directly

// handled by $dev_logger
$logger->info('Testing a var {my_var}', array('my_var' => array(...)));

Log levels

The eight RFC 5424 levels of logs are supported, in cascading order:

Severity Description
Emergency System level failure (not application level)
Alert Failure that requires immediate attention
Critical Serious failure at the application level
Error Runtime errors, used to log unhandled exceptions
Warning May indicate that an error will occur if action is not taken
Notice Events that are unusual but not error conditions
Info Normal operational messages (no action required)
Debug Verbose info useful to developers for debugging purposes (default)

Installation

Install the current major version using Composer with (recommended)

$ composer require apix/log:1.1.*

Or install the latest stable version with

$ composer require apix/log

License

APIx Log is licensed under the New BSD license -- see the LICENSE.txt for the full license details.