StimLog - Logging framework for PHP
StimLog is a logging framework for PHP., (*1)
You can easily configure StimLog to change the active log level and thus change
the behavior of your loggers without modifying your code., (*2)
Its main characteristics are the following:, (*3)
- Class based
- Trace the class and the line that triggered the log
- Easily configurable to:
- change the active loggers of your application
- change the active log level used in your application
- Easily extendable to add new components (
Writers and Formatters)
- A PSR-3 compliant logger is provided
Core concepts
Every Logger instance is dedicated to a class, which makes StimLog a logging framework only for PHP classes., (*4)
A Logger has a list of Writers (sometimes called Handlers or Appenders) that will handle the log data.
Several Writers are provided, but you are free to provide yours (they will have to extend the LogWriter abstract class)., (*5)
Each Writer has one Formatter, a component used to process the messages and display it in a particular form.
Several Formatters are provided, but you are free to provide yours (they will have to implement the LogFormatter interface)., (*6)
Last but not least, a configuration is required to activate loggers of your code at a specific level, and with specific Writers.
This configuration makes it possible to easily change the behavior of your loggers among your application, in a quick way.
This congifuration part is freely inspired from the well-known Java logging framework: log4j, (*7)
Usage
Step 1: Logging in a PHP class
StimLog loggers have to be created using the Logger::create() operation, and giving the client class name as an argument., (*8)
Then, the loggers provide operations to log information with different levels., (*9)
``` php
<?php, (*10)
namespace Example;, (*11)
use StimLog\Logger\Logger;, (*12)
class Foo {, (*13)
public function bar() {
// First, instantiate the logger and give the class name as argument
$logger = Logger::create(__CLASS__);
// Log data
$logger->error("This is an error");
$logger->notice("This is a notice");
}
}, (*14)
Step 2: Configuration
---------------------
StimLog relies on configuration settings that have to be set.
This settings are defined with a plain PHP `array`.
Each entry of this array will define one or multiple loggers'configuration (another `array`), through 3 settings:
- the namespace identifying the loggers
- the active level to use for the identified loggers
- the `Writer`s to use for the identified loggers
See the example below (used in our example as `stimlog.conf.php`):
``` php
<?php
// Loggers configuration
$loggers = array(
// First loggers'configuration
array (
// This configuration will concern every logger under the Example namespace
'class'=>'Example',
// This configuration will trigger all loggers with debug level or higher
'level'=>'debug',
// The list of writers for this configuration
'writers'=>array('StimLog\Writer\FileWriter')
),
);
Finally, you have to indicate StimLog the configuration file you want to use., (*15)
The LoggerManager::setup() operation is provided to do that., (*16)
``` php
<?php, (*17)
use StimLog\Manager\LoggerManager;, (*18)
LoggerManager::setup('/path/to/stimlog.conf.php');, (*19)
Advanced Usage
==============
Log levels
----------
StimLog supports the log levels described by [RFC 5424](http://tools.ietf.org/html/rfc5424).
- **DEBUG** (100)
- **INFO** (200)
- **NOTICE** (250)
- **WARNING** (300)
- **ERROR** (400)
- **CRITICAL** (500)
- **ALERT** (550)
- **EMERGENCY** (600)
Detecting the log level
-----------------------
StimLog loggers provide operations to detect the active log level.
Thus, you can use methods such as `isDebugEnabled()` (for the `DEBUG` level) to test if the concerned level is active.
``` php
if ($logger->isDebugEnabled()) {
// Perform debug operations...
}
Log operations
StimLog default logger provides different ways of logging information., (*20)
Basically, it is possible to log 3 types of data:, (*21)
- a
string, representing the message to log
- an
Exception
- an associative
array, containing some extra values for the log (called here context)
Logging with 1 argument
You can use the logging operations to log one parameter:, (*22)
``` php
// Log a message
$logger->notice("Just a notice");, (*23)
or
- an `Exception`
``` php
try {
throw new \Exception("An exception occurred!!!");
}
catch (\Exception $e) {
// Log an exception
$logger->error($e);
}
Logging with 2 arguments
You can use the logging operations to log two parameters:, (*24)
- a message (as a
string)
- an
Exception
``` php
try {
throw new \Exception("An exception occurred!!!");
}
catch (\Exception $e) {
// Log an exception
$logger->error("An exception occurred as expected", $e);
}, (*25)
or
- a message (as a `string`)
- a list of context values (as an associative `array`)
``` php
// Log a message
$logger->notice("Just a notice", array('user'=>$user, 'booleanValue'=>false));
or, (*26)
- an
Exception
- a list of context values (as an associative
array)
``` php
try {
throw new \Exception("An exception occurred!!!");
}
catch (\Exception $e) {
// Log an exception
$logger->error($e, array('user'=>$user, 'booleanValue'=>false));
}, (*27)
### Logging with 3 arguments
You can use the logging operations to log three parameters:
- a message (as a `string`)
- an `Exception`
- a list of context values (as an associative `array`)
``` php
try {
throw new \Exception("An exception occurred!!!");
}
catch (\Exception $e) {
// Log an exception
$logger->error("An exception occurred as expected", $e, array('user'=>$user, 'booleanValue'=>false));
}
PSR-3 compliant logger
Alternatively to the default StimLog logger, a PSR-3 compliant
logger is provided., (*28)
It is the StimLog\Logger\Psr3Logger., (*29)
About
Requirements
StimLog works with PHP 5.3 or above., (*30)
Author
Nicolas Hervé - nherve@gmail.com, (*31)
License
StimLog is licensed under the MIT License - see the LICENSE file for details., (*32)
Wallogit.com
