cadorn / monolog

Logging for PHP 5.3

Monolog - Logging for PHP 5.3

Usage

use Monolog\Logger;
use Monolog\Handler\StreamHandler;

// create a log channel
$log = new Logger('name');
$log->pushHandler(new StreamHandler('path/to/your.log', Logger::WARNING));

// add records to the log
$log->addWarning('Foo');
$log->addError('Bar');

Core Concepts

Every Logger instance has a channel (name) and a stack of handlers. Whenever you add a record to the logger, it traverses the handler stack. Each handler decides whether it handled fully the record, and if so, the propagation of the record ends there.

This allow for flexible logging setups, for example having a FileHandler at the bottom of the stack that will log anything to disk, and on top of that add a MailHandler that will send emails only when an error message is logged. Handlers also have a bubbling property which define whether they block the record or not if they handled it. In this example, setting the MailHandler's $bubble argument to true means that all records will propagate to the FileHandler, even the errors that are handled by the MailHandler.

You can create many Loggers, each defining a channel (e.g.: db, request, router, ..) and each of them combining various handlers, which can be shared or not. The channel is reflected in the logs and allows you to easily see or filter records.

Each Handler also has a Formatter, a default one with settings that make sense will be created if you don't set one. The formatters normalize and format incoming records so that they can be used by the handlers to output useful information.

Custom severity levels are not available. Only six levels (debug, info, warning, error, critical, alert) are present for basic filtering purposes, but for sorting and other use cases that would require flexibility, you should add Processors to the Logger that can add extra information (tags, user ip, ..) to the records before they are handled.

Docs

Handlers

• StreamHandler: Logs records into any php stream, use this for log files.
• RotatingFileHandler: Logs records to a file and creates one logfile per day. It will also delete files older than $maxFiles. You should use logrotate for high profile setups though, this is just meant as a quick and dirty solution.
• FirePHPHandler: Handler for logging simple strings to a browser console (FireBug + FirePHP Extension or DeveloperCompanion) using the firephp/wildfire header protocol.
• InsightHandler: Handler for logging objects and detailed intelligence data to a browser tool that supports the Insight Intelligence System. DeveloperCompanion is the most advanced supporting client at this time while FireBug + FirePHP Extension provide logging to a single console. NOTE: To use this handler the FirePHP 1.0 library must also be installed (see below). If FirePHP 1.0 is not installed and activated any messages logged to this handler will be ignored silently.
• NativeMailHandler: Sends emails using PHP's mail() function.
• SwiftMailerHandler: Sends emails using a SwiftMailer instance.
• SyslogHandler: Logs records to the syslog.

Wrappers / Special Handlers

• FingersCrossedHandler: A very interesting wrapper. It takes a logger as parameter and will accumulate log records of all levels until a record exceeds the defined severity level. At which point it delivers all records, including those of lower severity, to the handler it wraps. This means that until an error actually happens you will not see anything in your logs, but when it happens you will have the full information, including debug and info records. This provides you with all the information you need, but only when you need it.
• NullHandler: Any record it can handle will be thrown away. This can be used to put on top of an existing handler stack to disable it temporarily.
• BufferHandler: This handler will buffer all the log records it receives until close() is called at which point it will call handleBatch() on the handler it wraps with all the log messages at once. This is very useful to send an email with all records at once for example instead of having one mail for every log record.
• GroupHandler: This handler groups other handlers. Every record received is sent to all the handlers it is configured with.
• TestHandler: Used for testing, it records everything that is sent to it and has accessors to read out the information.

Formatters

• LineFormatter: Formats a log record into a one-line string.
• JsonFormatter: Encodes a log record into json.
• WildfireFormatter: Used to format log records into the Wildfire/FirePHP protocol, only useful for the FirePHPHandler.

Processors

• WebProcessor: Adds the current request URI, request method and client IP to a log record.

Logging with the InsightHandler

Required: FirePHP 1.0 on server and Firefox on client.

To use FirePHP 1.0 configure and load it (See here or use the DeveloperCompanion New Workspace wizard):

define('INSIGHT_IPS', '*');       // <- CHANGE THIS
define('INSIGHT_AUTHKEYS', '*');  // <- CHANGE THIS
define('INSIGHT_PATHS', dirname(__DIR__));
define('INSIGHT_SERVER_PATH', '/');
require_once('phar://firephp.phar/FirePHP/Init.php');

Install DeveloperCompanion or FireBug + FirePHP Extension.

Configure InsightHandler:

// Log to the 'page' context. i.e. DeveloperCompanion Console or Firebug Console
$log->pushHandler(new InsightHandler(array(
    'context' => 'page'      // default
)));

// Log to the 'request' context. i.e. DeveloperCompanion Window
$log->pushHandler(new InsightHandler(array(
    'context' => 'request',
    'console' => 'Monolog Console'  // title for console
)));
// TIP: Open the workspace for your application in DeveloperCompanion to see requests
// TIP: When logging to the request context you can set up multiple loggers
//      that target differently titled consoles.

// See Insight API at http://reference.developercompanion.com/#/Tools/FirePHPCompanion/API/
InsightHandler::getContext('page')->console()->log('Hello World');

For support using the InsightHandler see: http://groups.google.com/group/firephp-dev

About

Requirements

Any flavor of PHP 5.3 should do

Submitting bugs and feature requests

Bugs and feature request are tracked on Github

Author

Jordi Boggiano - [email protected] - http://twitter.com/seldaek
See also the list of contributors which participated in this project.

License

Monolog is licensed under the MIT License - see the LICENSE file for details

Acknowledgements

This library is heavily inspired by Python's Logbook library, although most concepts have been adjusted to fit in the PHP world.