phpLogFacility (a working log4php) Files

Program:	phpLogFacility
Version:	0.10
Author:		Manuel Hoppe (m.hoppe@hyperspeed.de)
Homepage:	http://sourceforge.net/projects/phplogfacility
Copyright:	GPL, see http://www.fsf.org/licenses/licenses.html#GPL
Description:	Logging mechanism for PHP programs

Wishlist: If you are missing something, please mail me!

###########################################################################

IMPORTANT:
New interface methods are introduced with this release. Please use *only*
the new interface methods described below and adapt your source if needed!

###########################################################################


Table of Contents:
1 - Precautions
2 - Examples
2.1 - Code Sample
2.2 - Available preconfigured classes
3 - Usage
3.1 - Instance Log File
3.2 - Available Log Levels
3.3 - Write to Log File
3.4 - File Rotation
3.5 - Log Format
3.6 - Log File Compression
3.7 - EMail Alerts
3.8 - Set Write Buffer
3.9 - Set Message Buffer
3.10 - Get phpLogFacility Version
4 - Custom Log Classes
5 - What is this $logID Good For?


1 - Precautions
===============
Make sure target log directory is writeable for the writing user! With
Apache+PHP its not nessessarely your upload user. If unsure, and you
really trust your enviroment and all users on the system (!) make the log
directory writeable for everyone ("chmod 777 /log/dir").


2 - Examples
============

2.1 - Code Sample
-----------------
$log = new newphpLogFacilityWebSimple ( "/path/to/file.log", "DEBUG", "myscript" );
$log->write ( "my message" ); // default level: NOTICE 
$log->warning ( "my warning" );
$log->write ( "my warning", "WARNING" ); // alternative for the line above
$log->crit ( "my warning with php backtrace", debug_backtrace () );
$log->write ( "my warning with php backtrace", "CRIT", debug_backtrace () );
$log->close ();

2.2 - Available preconfigured classes
-------------------------------------
newphpLogFacility = good for console applications
newphpLogFacilityWeb = complex web applications on multiple web server
newphpLogFacilityWebSimple = default web application (I bet you want THIS! :-) )
newphpLogFacilityMultipleFiles = a log file for each log level
See next chapters for detailed descriptions.


3 - Usage
=========

3.1 - Instance Log File
-----------------------
Usage:
$log = new newphpLogFacility ( $logfile, $level, $section );
$log = new newphpLogFacilityMultipleFiles ( $filePrefix, $filePostfix, $level, $section );
Notes:
All arguments are optional. $logfile name is by default
"./phpLogFacility.log", $level is by default "DEBUG" and $section is the
name of the calling script.
For newphpLogFacilityMultipleFiles $filePrefix is by default
"phpLogFacility." and $filePostfix ".log". So the full composed name of the
default log files are "phpLogFacility.debug.log" and so on.
See chapter 2.2 for available predefined log objects.

3.2 - Available Log Levels
--------------------------
The log levels are borrowed by the well known syslog:
* EMERG	(component is unusable)
* ALERT (action must be taken immediately)
* CRIT (critical conditions)
* ERR (error conditions)
* WARNING (warning conditions)
* NOTICE (normal, but significant, condition)
* INFO (informational message)
* DEBUG (debug-level message)
If you send any other string send to phpLogFacility will be reseted to
WARNING level.

3.3 - Write to Log File
-----------------------
Usage:
$this->write ( $message, $level, $dump ); 
or:
$this->debug ( $message, $dump );
-> $this-><errorlevel> ( $message, $dump );
Notes:
$level and $dump are optionally. If $level is not supplied, "NOTICE" is
assumed.
Please note, that you can not just supply a debug_backtrace () dump, you can
virtually anything put in here. If this argument is a array, its written
like a var_dump () output. So if you have special variables that won't fit
into a normal line (database results, etc), place this as third argument for
$log->write ().

3.4 - File Rotation
-------------------
Usage:
$this->setRotation ( $size, $archives );
Description:
By default, $archives is set to twelve and $size to 51200 Bytes. 
$archives will be kept, this cant be set smaller than one archive.
If the Log file is greater than $size, the log file will be rotated. This
can't be smaller than 1024 Bytes.

3.5 - Log Format
----------------
Usage:
$this->setMask ( $mask );
$mask should contain your desired log format and your needed placeholders:
* %REMOTE_IP% (remote IP)
* %MY_IP% (server IP, web applications only)
* %NAME% (custom name)
* %LEVEL% (error level)
* %DATE% (recent date)
* %PID% (PHP script process ID)
* %MSG% (log message content)
* %LOGID% (unique Log ID, also return value after each write () )
Example:
$this->setMask ( "%NAME%\t%DATE%\t%REMOTE_IP%\t%LEVEL%\t%MSG%" );

3.6 - Log File Compression
--------------------------
Usage:
$this->setCompression ( $compressionType );
Description:
You can enable log file compression. All new files will be rotated and
compressed. Please note that old rotated files won't be compressed or
recompressed.
File compression is off by default. If you call setCompression () without
any arguments, "gz" compression is assumed. You can choose between "gz"
(gzip) or "bz2" (bzip2) compression. Gzip is the well known "old"
compression method. Bzip2 is more advanced and more efficent, but also
needs more ressources.
To switch compression off, use anything else as method argument (eg.
"off").
WARNING: enabled compression could be a serious performance issue, with
can lead to significant longer execution times of your scripts. $size of
setRotation () shouldn't be too large. Also, gzip or bzip2 support need
to be compiled for your PHP version. If unsure, ask your system
administrator.

3.7 - EMail Alerts
------------------
Usage:
$this->setMailAlert ( $level, $email );
Description:
If you set this, you receive for all log entries equal or higher than $level
an email (see chapter 3.1 for available log levels).
This feature is disabled by default.

3.8 - Set Write Buffer
----------------------
Usage:
$this->setWriteBuffer ( $length );
Description:
This is the best way to boost the write performance of phpLogFacility. If
you set this to "0" (default), all data is directly written to disk ($length
in Bytes). You might want so set this to something higher, especially an
busy sites. But note, that also rotated files are at least $length Bytes
bigger.

3.9 - Set Message Buffer
------------------------
Usage:
$this->setMessageBuffer ( $rows );
Description:
Another way to boost your performance is to set the message buffer. $rows
number of log entries will be buffered (default 3) before they are written
to disk. Your log files might grow slightly before it will be rotated.

3.10 - Get phpLogFacility Version
---------------------------------
Usage:
$this->getVersion;
Description:
If you need to check the version of phpLogFacility (eg. for compatibily
reasons), use this method.


4 - Custom Log Classes
----------------------
If you create your own class, please always call $this->init(). This
methode makes sure, that all values are set to valid defaults.


5 - What is this $logID Good For?
---------------------------------
With every $this->write () you get a md5 checksum. This identifies your
log entry, it's unique.
I use this in web projects to display a error page and refer to this
checksum. If a visitor got such an error, I can easily track down the error
even on busy sites. You don't have to reveal sensitive data output or
something to anyone, the checksum is enough.
I think, it's a good thing (TM) ;-)