README

APIx Log, very thin PSR-3 logger

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:
  • PHPMailer/apix-log-phpmailer ~ logs are sent using PHPMailer,
  • jspalink/apix-log-pushover ~ logs are sent using Pushover,
  • apix/log-tracker ~ adds logger/tracker such as Google Analytics, Dashbot, etc...,
  • More contributions will be linked here.
• Clean API, see the LoggerInterface and the LogFormatterInterface.
• 100% Unit tested and compliant with PSR0, PSR1 and PSR2.
• Continuously integrated against 7.0, 8.x, and HHVM (use ^1.1 for older PHP versions).
• 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

$urgent_logger = new Apix\Log\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 Apix\Log\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 Apix\Log\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 Apix\Log\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:

Installation

Install the current major version using Composer with (recommended)

composer require apix/log:1.3.*

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.