Overview of flog()
When writing PHP code, that will be included in other people’s code (like plugins, widgets, callbacks, or callback pages), debugging is usually done with log files. This way you will not break the page structure and you can output stuff to your hearts content.
The simple error_log() that PHP provides, is not helpful enough in most of the cases, because it does not automatically log the context of where the function was called. If for example you have multiple if branches in your code and you just want to check what branches are followed, you would need to log a unique message in each branch.
When writing code, coming up with unique log messages is not the best way to spend your creativity and you end up with things like “crap”, “wft!?!”, “jeez”, “crap2″ and so on…
With the flog() function a simple call to flog(), with no parameters, will write enough data in the log file so you can determine exactly where that log comes from. It’s all about context.
Here is what flog() can do for you:
- log the file name and line in that file where the function was called
- log the stack trace
- log the time stamp
- it can print objects, arrays, simple strings and even support the sprintf() formats.
- can be called with no parameters, just to leave a “trace” in the log file
- auto indents multi-line logs for easy reading. For example objects and arrays.
- can be configured to automatically disable itself when script runs on live server
How to use it
To use flog() you just have to include (include/require) the “flog.php” file and then just do flog() calls.
Below are some examples:
//do your config - OPTIONAL define( "FLOG_SHOW_STACK", true ); define( "FLOG_CLEAR_LOG", true ); //include the source file require( "flog.php" ); $obj = new stdclass(); $obj->a = array( "p1" => 10.0, "p3" => 10.0 ); $array = array( "option1", "option2" ); //example of different calls flog( ); flog( $obj ); flog( $array ); flog( "Value for text is: %5.2f %s.", 11.113, "BOO!" );
The function is pre-configured to work well out of the box, but you can still customize it, if you wish.
Configuration is done with “define”, defining true/false values for most flags and some string values for others.
Available configuration flags:
- FLOG_IGNORE – set to true to disable flog() (default is false)
- FLOG_SHOW_TIME – true shows time stamp in logs (default is true)
- FLOG_SHOW_STACK – true shows call stack in logs (default is false)
- FLOG_CLEAR_LOG – when true the log file gets cleared at every page loag (default is false)
- FLOG_STRIP_PATH – the string you define here will be removed from the script file name, making the log line much shorter. This should be set to your web root. (default is your web-root)
- FLOG_ONLINE_SERVER – if you set here the name of your production server, flog will disable itself on that server. (default is “softconsultant.ro”)
- FLOG_FILE_NAME – the name of the log file (default is “flog.log”)
Log file location is always in the same folder as the “flog.php” file.