*************************************************************************
* NmnLogger ver. 1.0 *
* author: Ivan Preziosi (ivan@netmeans.net) *
* release date: May 2006 *
* this software is released under LGPL license. *
* Look for the LICENSE file in the root directory of the package *
* for details about licensing, or go to the free software *
* foundation site at: *
* http://www.gnu.org/licenses/licenses.html#LGPL *
*************************************************************************
DESCRIPTION:
NmnLogger is a small set of classes developed to create a simple but yet
effective logging mechanism, giving the ability to create complex and
functional logging systems within minutes.
NmnLogger relies on a small xml config file, where you can set up all your
logging preferences.
I works correctly only with a php 5.x realease.
PACKAGE ELEMENTS:
NmnLogger.php:
Utility class which wraps common calls to the engine in some static functions.
Intended to speed up the use of the application in development.
NmnLoggerObject:
The main engine class, must be instantiated before every logging. You can use
the static functions in NmnLogger.php to save development time.
NmnLoggerConfig:
This class takes care of reading the config file and storing the information
for use within the package.
NmNLoggerDevice:
This object represent logging devices created via the xml config file. Every
logging device can have it's own logging level, which is the level of priprity
the log message has been given. Only messages with a priority level higher than
or equal to the one given to any single device will be processed.
NmnMessageFactory:
This class takes care of creating the actual log message given a string or a
Exception object. The message object has also it's own priority level.
Any custom message factory must extend the base NmnMessageFactory. You can write
your own factory to process messages the way you want. Message factory to be used within
the application is specified in the 'nmn-logger-config.xml' file.
The default NmnMessageFactory class implements a message map to let you define the format
the log message should have. You can specify logs format in the nmn-logger-config.xml file, as the
content of the message-factory node.
Ex. [%date% %time%]%message% - File:%file% - %BR%
The variables you can use in the message format string are:
%date% = the date the log is issued
%time% = the time the log is issued
%message% = the actual log message (or exception message if logging exception)
%file% = the file wich fired the log
%code% = the exception error code (if logging an exception)
%trace% = the exception trace (with getTraceAsString()) (if logging an exception)
%line% = the exception line (if logging an exception)
%logLevel% = the message log level
%BR% = a line break in the message
nmn-logger-config.xml:
This is the configuration file used to setup the logger.
Drivers:
The main engine relies on Driver classes to dispath the logs to all
available media. Every class can be configured directly into the class file.
At the moment four drivers are available:
NmnLoggerBaseDriver.php: used to log onscreen, within the output of your application,
makes use of echo statemens to print out log messages.
NmnLoggerFileDriver.php: used to log to a text file.
NmnLoggerMailDriver.php: this driver makes use of the phpMailer (http://phpmailer.sourceforge.net/)
library to dispatch logs to any mail recipient.
NmnLoggerMysqlDriver.php: used to log directly into a mysql database.
You can write your own drivers to dispatch messages to any medium. To do that you have to
extend the NmnLoggerBaseDriver class and implement your own doLog() function.
INSTALLATION
Installing and running the logger is a simple and fast process. We will go throu
the installatin procedure step by step:
1)Copy the "logger" folder to your application file system. It can be placed in any
location, but you must include the folder containing it in the include path.
2)Edit the nmn-logger-config.xml file. It will ship something like that:
<?xml version="1.0"?>
<logger-config version="NMNL:1.1">
<message-factory class="logger.messageFactories.NmnMessageFactory" outputTemplate="[%date% %time%]%message%- {%file%}%BR%" />
<logger-family id="default">
<logger-device level="1">
<!-- <driver class="logger.drivers.NmnLoggerBaseDriver">NmnLoggerBaseDriver</driver> -->
<!-- <driver class="logger.drivers.NmnLoggerFileDriver">NmnLoggerFileDriver</driver> -->
<driver class="logger.drivers.NmnLoggerMysqlDriver">NmnLoggerMysqlDriver</driver>
<!-- <driver class="logger.drivers.mailLogger.NmnLoggerMailDriver">NmnLoggerMailDriver</driver> -->
</logger-device>
</logger-family>
</logger-config>
message-factory: this is the message factory class defined to process messages. You can write your own messageFactory class
(remember to extend the NmnMessageFactory class) or use the default one provided along with the package.
The default message factory class shipped with the package has it's own message definition format used to declare the
message's appearance.
Ex. [%date% %time%]%message% - File:%file% - %BR%
The variables you can use in the message format string are:
%date% = the date the log is issued
%time% = the time the log is issued
%message% = the actual log message (or exception message if logging exception)
%file% = the file wich fired the log
%code% = the exception error code (if logging an exception)
%trace% = the exception trace (with getTraceAsString()) (if logging an exception)
%line% = the exception line (if logging an exception)
%logLevel% = the message log level
%BR% = a line break in the message
logger-family: this is the macro group of devices registered to the logger. Most of the time you will have
only one family per project. Using the static functions to log will send your logging to the "default" family.
If you want to implement more families to log on you can do it creating more logger-family nodes in your config.
You can then address the right family to log to in the constructor of the NmnLoggerObject class.
logger-device: Logger device group by logger drivers which will share the same priority level. Sending a log to a family
will affect only the devices with a priority level smaller than or equal to the one in your logging message.
You can define more than one logger device to dispath logs to various drivers depending on the priority level.
driver: the driver takes care of writing the log message to the appropriate media. Some drivers need extra parameters
to function properly, for example the FileLogger class needs to be declared the path to store the files, and a prefix
to identify the log files. Log files are generated on a day to day basis having their date written within the filename.
If no parameters are given the driver can supply default values or halt depending on it's internal structure.
If the specified folder to store logfiles does not exist the program will prompt an error.
USAGE
BASIC USAGE: You have two static functions defined in the NmnLogger Class to log simple messages.
You'll call NmnLogger::logException(Exception $e, $level = 1) to automatically generate a log message from a Exception object.
You can also call NmnLogger::logString($e, $level = 1) to generate a log message from any string or numeric value.
If you plan to log multiple times during a single script it's more efficient to instantiate a NmnLoggerObject class.
You can then call the NmnLoggerObject->logString() or the NmnLoggerObject->logException() as many thimes as you want
passing proper parameters to log.
Ex.
$myLogger = new NmnLoggerObject();
$myLogger->logString($e,1);
//some code here
try{
// some code here
}catch(Exception $ex){
$myLogger->logException($e,1);
}
DRIVERS DESCRIPTION:
-)NmnLoggerBaseDriver driver:
The NmnLoggerMailDriver driver is the simplest of all the drivers shipped with the package. It simply relies on
echo statements to print out the log message on screen. It's good for development time or to display
errors to the end user. It's also the base class that all drivers must extend.
-)NmnLoggerFileDriver driver:
The NmnLoggerFileDriver is the most commonly used driver by any logging package. It's developed to log messages on
a log file (txt file). Unlike the NmnLoggerMailDriver driver it needs some extra parameters to function properly:
"filePath": It's the path where the logfiles created will be saved. It's definition must start from
the "logger/" folder, or any other folder located in the include path. If omitted defaults to
'logger/fileLogs/'. Keep in mind that if you define a non existant folder the application will
throw an exception!
"fileName" The actual name the log file will have. For example chosing 'campLogAppLogs' as a file name
will result as having files like 'campLogAppLogs23_05_2006.log" where the log date will be
appended to the chosen filename. The file extension will be .log.
-)NmnLoggerMailDriver driver:
The NmnLoggerMailDriver driver can be used to dispatch log messages to any mail recipient. This class makes use of the
PHPMailer library (http://phpmailer.sourceforge.net/) to generate and send emails. The needed params used to
configure and create mails are specified in the nmn-logger-config.xml. Those parameters are:
"mailSenderName"This parameter is used to define the log email sender name information.
"mailSenderAddress" This parameter is used to define the log email sender address.
"mailSenderHost" This parameter is used to define the log email SMTP server host.
"phpmailMode" This parameter is used to define the log email php mail mode as defined in the phpMailer
documentation (Method to send mail: ("mail", "sendmail", or "smtp")).
"mailRecipients" List of the mail recipients that will receive the log message (separated by a ',').
"mailSubject" The subject the log email will have.
-)NmnLoggerMysqlDriver driver:
This driver can be used to log directly into a mysql db. You can set the connection parameters directly in the class.
There is a optional parameter "dateTimeFieldInTable" that you can use to switch on or off direct date loggin to a datetime field.
|
Download
