|
|
|
[PHP5] ODEBUGGER PACKAGE
o This package is a debugging and helper tool.
o It overrides the errors and exceptions handling by PHP.
o Errors are generated, even if error_reporting is set to 0.
o Errors are translated in a more comprehensive way, and hints for a correction is displayed.
o Errors can be displayed realtime, and/or logged in an XML file.
o This tool can be used by beginners, because it gives them a more comprehensive error message, and hint to debug their code. Gurus can personalize it to fit their needs.
It's easy to use, you can find some examples in all the indexN.php pages.
Version 20060612
- Localized in : French, English (ENglish being the default language)
- Many errors translated and hinted
- Error types translated
- 2 different kinds of display : the Realtime mode, and the Stats mode.
- Easyly configurable : translations, new error messages, hints, display and so on.
HOW TO :
* How to call the debugger :
| $oDebugger = new odebugger ('EN');
Where 'EN' is the chosen language.
Check the 'xml/' folder to see which languages are currently supported.
English being the default language, you can call the debugger this way, too, for English :
$oDebugger = new odebugger; | |
* How to add a new language :
| In the xml/ folder, you can find surbolders. Each one contains the XML
files for a different language.
'EN/' => English
'FR/' => French.
If you want to add, for example, German, just create a 'GE/' subfolder,
and copy both the xml files : errors.xml and types.xml into the new
folder and edit them. All you have to do is change the <translation>
and <suggestion> nodes in the XML files And that's it!
You can then call the debugger in German :
$oDebugger = new odebugger ('GE'); | |
How to add a new error :
| Well, just edit the chose language errors.xml file (xml/LANGUAGE/errors.xml), and copy/paste a node within the <errors></errors> root node. It must follow the others:
<error>
<label>Undefined index:</label>
<translation>An index has been used without being defined</translation>
<suggestion>Check the max and min limits of your array</suggestion>
</error>
Just change the values, save the file, and that's it. You can, of course,
also change an existing node, if you do not like my translations /
suggestions ;-) | |
* How to change the display:
| Well, there is currently 2 types of display : realtime, and stats.
IN the folder 'templates/', you can find some files. For example :
default.dat
default_log.dat
default.dat is the default realtime display HTML template, while default_log.dat is the default stat HTML template. You can create your own, of course. The information supplied by odebugger replace the {INFO_NAME} types of string. Just make sure you put all the information you want in your templates :-) For the stats template, there is a slight difference : it has 3 parts. The first one starts from the...start, and ends on : <--! LINES HERE -->. This part is fixed. These are the headers!
Then, between <--! LINES HERE -->. and <!-- STATS -->, the logs will be displayed. And of course, the lines here will be repeated as many times as you have lines in your log. Then, after <!-- STATS -->, you have your stats :-)
You can set new templates with the odebugger::HTML and odebugger::HTMLLOG properties. See the part of this documentation about the OPTIONS.
In the 'css/' folder, you can also find files. These are the CSS files use to modify the HTML templates.
default.dat being the CSS for the default.dat HTML template.
default_log.dat being the CSS for the default_log.dat HTML template.
You can also, of course, set them : odebugger::CSS and odebugger::CSSLOG | |
OPTIONS (Syntax) :
| $oDebugger -> {OPTION} = {VALEUR};
Foir example :
$oDebugger -> LINES = 2;
odebugger::LINES => integer : gives the number of source code lines to be displayed before and after the error line
default value : 2
odebugger::HTML => string with the name of the file for the HTML template, in the 'templates/' folder, without its extension.
Used to display the realtime log.
default value : 'default'
odebugger::CSS => string with the name of the file for the CSS template, in the 'css/' folder, without its extension.
Used to transform the HTML template for realtime log.
default value : 'default'
odebugger::HTMLLOG => string with the name of the file for the HTML template, in the 'templates/' folder, without its extension.
Used to display the stats log.
default value : 'default_log'
odebugger::CSSLOG => string with the name of the file for the CSS template, in the 'css/' folder, without its extension.
Used to transform the HTML template for stats log.
default value : 'default_log'
odebugger::REALTIME => boolean : true or false. Activate or de-activate the realtime mode (errors are displayed realtime)
default value : true
odebugger::LOGFILE => boolean : true or false. Activate or de-activate the saving of the log into an xml files (in 'logs/'). These can be displayed via odebugger::showLog () method, and loaded with the odebugger::loadXML () method.
default value : true
odebugger::ERROR => Boolean : true or false. Activate or de-activate the errors handling.
default value : true
odebugger::EXCEPTION => Boolean : true or false. Activate or de-activate the exceptions handling.
default value : true
You can also retrieve these values :
echo $oDebugger -> LINES; // displays 2 | |
METHODS (the ones you can call only) :
| odebugger::checkCode (string sString)
Used to check if there are any errors in a string (usually used by retrieving in a string the content of a file. See index3.php to see that in action).
odebugger::loadXML (string sFile)
Used to get an existing log from a file (logs are stored in the 'logs/' folder). This method erase any previous log (realtime or not).
odebugger::showAll ()
Used to display the whole current log, just as if it was in realtime mode. You can display a loaded log, or the current realtime log.
odebugger::showLog ()
Used to display the whole current log in stats mode. You can display a loaded log, or the current realtime log.
odebugger::saveToFile (optional string sFile)
Used to save the current log to a file. This methods is used automatically when the script ends, if odebugger::LOGFILE is set to true.But it can be called manually, with a filename. | |
odebugger.cls.php
| <?php
/**
* CLASS odebugger
*
* @author : johan <barbier_johan@hotmail.com>
*/
class odebugger {
/**
* private (string) sAssertion
* Check if error comes from an essertion or not, if yes, will conatin the filename of the evaluated script
*/
private $sAssertion = null;
/**
* private (string) sLang
* localization string
*/
private $sLang = 'EN';
/**
* private (int) iNbLines
* Number of lines displayed before and after the line of the error
*/
private $iNbLines = 2;
/**
* private (array) aOptions
* Options array
*/
private $aOptions = array (
'REALTIME' => true,
'LOG_FILE' => true,
'ERROR' => true,
'EXCEPTION' => true
);
/**
* private (string) sTemplateHTML
* HTML template file for the realtime log
*/
private $sTemplateHTML = 'default';
/**
* private (string) sTemplateCSS
* CSS template file for the realtime log
*/
private $sTemplateCSS = 'default';
/**
* private (string) sTemplateHTMLLOG
* HTML template file for the whole log file
*/
private $sTemplateHTMLLOG = 'default_log';
/**
* private (string) sTemplateCSSLOG
* CSS template file for the whole log file
*/
private $sTemplateCSSLOG = 'default_log';
/**
* private (string) sCurDir
* Current directory of the script
*/
private $sCurDir = '';
/**
* private (string) sCurId
* Current file unique id
*/
private $sCurId = '';
/**
* private (object) oXMLDOC
* XML LOG Object (DOMDocument object)
*/
private $oXMLDOC = null;
/**
* private (object) oXMLROOT
* XML LOG root Object (DOMDocument object)
*/
private $oXMLROOT = null;
/**
* private (object) oCurrentNode
* Current node Object (DOMDocument object)
*/
private $oCurrentNode = null;
/**
* private (array) aCanBeSet
* class properties that can be set via odebugger::__set()
*/
private $aCanBeSet = array (
'LINES' => 'iNbLines',
'REALTIME' => "aOptions['REALTIME']",
'LOGFILE' => "aOptions['LOG_FILE']",
'HTML' => 'sTemplateHTML',
'CSS' => 'sTemplateCSS',
'HTMLLOG' => 'sTemplateHTMLLOG',
'CSSLOG' => 'sTemplateCSSLOG',
'ERROR' => "aOptions['ERROR']",
'EXCEPTION' => "aOptions['EXCEPTION']"
);
/**
* private (object) oXMLTYPES
* XML DOMDocument object with the list of error types and their translation
*/
private $oXMLTYPES = null;
/**
* private (object) oXMLERRORS
* XML DOMDocument object with the list of errors and their translation
*/
private $oXMLERRORS = null;
/**
* private (array) aIndex
* replacement array for the templates
*/
private $aIndex = array (
0 => array (
'{DATE_TITRE}',
'{DATE_VALUE}'
),
1 => array (
'{TYPE_TITRE}',
'{TYPE_VALUE}'
),
2 => array (
'{MSG_TITRE}',
'{MSG_VALUE}'
),
3 => array (
'{FILE_TITRE}',
'{FILE_VALUE}'
),
4 => array (
'{LINE_TITRE}',
'{LINE_VALUE}'
),
5 => array (
'{MEM_TITRE}',
'{MEM_VALUE}'
),
6 => array (
'{TRANS_TITRE}',
'{TRANS_VALUE}'
),
7 => array (
'{SUGG_TITRE}',
'{SUGG_VALUE}'
),
8 => array (
'{CONTEXT_TITRE}',
'{CONTEXT_VALUE}'
),
9 => array (
'{SOURCE_TITRE}',
'{SOURCE_VALUE}'
),
100 => '{TOTAL_STATS}',
101 => '{PHP_VERSION}'
);
/**
* public function __construct ()
* contsructor
* sets the error_reporting to 0
* gets the localization dir
* import all the xml files
* set the error handler
* @Param (string) sLang : the localization used
*/
public function __construct ($sLang = 'EN') {
@error_reporting (0);
$aLnDir = scandir ('xml');
if (in_array ($sLang, $aLnDir)) {
$this -> sLang = $sLang;
}
$this -> oXMLERRORS = DOMDocument::load ('xml/'.$this -> sLang.'/errors.xml');
$this -> oXMLTYPES = DOMDocument::load ('xml/'.$this -> sLang.'/types.xml');
$this -> oXMLDOC = new DOMDocument ('1.0', 'utf-8');
$root = $this -> oXMLDOC -> createElement ('ERRORLOG');
$this -> oXMLROOT = $this -> oXMLDOC -> appendChild ($root);
if (!is_dir ('logs')) {
@mkdir ('logs', 0744);
}
$sTemp = dirname (__FILE__);
$aTemp = explode ('\\', $sTemp);
array_pop ($aTemp);
$this -> sCurDir = implode ('/', $aTemp).'/';
$this -> sCurId = date ('Ymd').'_'.uniqid();
set_error_handler (array ($this, 'myErrorHandler'));
set_exception_handler (array ($this, 'myExceptionHandler'));
}
/**
* public function checkCode ()
* use the assert () function to get the errors in a given string, or a given file
* @Param (string) sString : the string with the PHP code to evaluate, or the file to evaluate. Usually, it will come from a file via file_get_contents () for example
* @Return : false if given parameter is not a string.
*/
public function checkCode ($sCode) {
if (file_exists ($sCode)) {
$sString = file_get_contents ($sCode);
$this -> sAssertion = $sCode;
} elseif (!is_string ($sCode)) {
return false;
} else {
$sString = $sCode;
}
$sString = str_replace (array ('<?php', '<?', '?>'), '', $sString);
assert_options(ASSERT_ACTIVE, 1);
assert_options(ASSERT_WARNING, 0);
assert_options(ASSERT_QUIET_EVAL, 1);
//assert_options (ASSERT_CALLBACK, array ($this, 'myAssertHandler')); Waiting a bit to improve this part
assert ($sString);
assert_options(ASSERT_ACTIVE, 0);
}
/**
* public function myAssertHandler ()
* activate the assertion. Right now, does nothing...and is not used.
* @Param (string) file : the file from which comes the code
* @Param (int) line : the error line
* @Param (string) code : the error code
* @Return : true
*/
public function myAssertHandler ($file, $line, $code){
return true;
}
/**
* private function checkErrorMessage ()
* try to find the correct trsnalation and suggestion from a given error message
* @Param (string) sMsg : the PHP error message
* @Return (array) aTempArr : array with the translation and the suggestion found
*/
private function checkErrorMessage ($sMsg) {
$iLength = strlen ($sMsg);
$xpath = new DOMXPath($this -> oXMLERRORS);
$sQueryLabel = '//error/label';
$oLabelLists = $xpath -> query ($sQueryLabel);
$aMsg = explode (' ', $sMsg);
foreach ($oLabelLists as $oLabel) {
$aLabel = explode (' ', $oLabel -> nodeValue);
$aDiff = array_diff ($aLabel, $aMsg);
if (empty ($aDiff)) {
$aTempArr['TRANSLATION'] = $oLabel -> nextSibling -> nextSibling -> nodeValue;
$aTempArr['SUGGESTION'] = $oLabel -> nextSibling -> nextSibling -> nextSibling -> nextSibling -> nodeValue;
return $aTempArr;
}
}
}
/**
* private function checkTypeTrans ()
* try to find the error type translation
* @Param (int) cErrno : the PHP constant error type code
* @Return (string) nodeValue : the translated error type
*/
private function checkTypeTrans ($cErrno) {
$xpath = new DOMXPath($this -> oXMLTYPES);
$sQueryLevel = '//type/level';
$oLevelList = $xpath -> query ($sQueryLevel);
foreach ($oLevelList as $oLevel) {
if (constant ($oLevel -> nodeValue) === $cErrno) {
return $oLevel -> nextSibling -> nextSibling -> nodeValue;
}
}
}
/**
* public function myExceptionHandler ()
* the exception handler : builds the XML error log
* @Param (object) e : the Exception object
*/
public function myExceptionHandler ($e) {
$sErrStr = $e -> getMessage ();
$iErrLine = $e -> getLine ();
$sType = 'Exception '.$e -> getCode ();
if (is_null ($this -> sAssertion)) {
$sErrFile = $e -> getFile ();
} else {
$sErrFile = $this -> sAssertion;
$this -> sAssertion = null;
}
$sVars = $e -> getTraceAsString ();
$aTempArr = array ('TRANSLATION' => '', 'SUGGESTION' => '');
$this -> buildLog ($sType, $sErrStr, $sErrFile, $iErrLine, $aTempArr, $sVars);
}
/**
* public function myErrorHandler ()
* the error handler : builds the XML error log
* @Param (int) cErrno : the PHP constant error type code
* @Param (string) sErrStr : the PHP error message
* @Param (string) sErrFile : the file in which the error has been detected
* @Param (int) iErrLine : the line of the error
* @Param (array) mVars : the context
*/
public function myErrorHandler ($cErrno, $sErrStr, $sErrFile, $iErrLine, $mVars) {
$aTempArr = $this -> checkErrorMessage ($sErrStr);
$sType = $this -> checkTypeTrans ($cErrno);
$sVars = 'n/a';
if (!is_null ($this -> sAssertion)) {
$sErrFile = $this -> sAssertion;
$iErrLine ++;
$this -> sAssertion = null;
}
$this -> buildLog ($sType, $sErrStr, $sErrFile, $iErrLine, $aTempArr, $sVars);
}
/**
* private function buildLog ()
* the error handler : builds the XML error log
* @Param (string) sType : The type of error/exception
* @Param (string) sErrStr : the PHP error message
* @Param (string) sErrFile : the file in which the error has been detected
* @Param (int) iErrLine : the line of the error
* @Param (string) sVars : the context
*/
private function buildLog ($sType, $sErrStr, $sErrFile, $iErrLine, $aTempArr, $sVars) {
$iErrLine --;
if ($iErrLine < 0) {
$iErrLine = 0;
}
$oNewLog = $this -> oXMLDOC -> createElement ('ERROR');
$dump = $this -> oXMLROOT -> getElementsByTagName('ERROR');
$iNewId = $dump -> length + 1;
$oNewLog = $this -> oXMLROOT -> appendChild ($oNewLog);
$oNewLog -> setAttribute ('xml:id', '_'.$iNewId);
$aElem[] = $this -> oXMLDOC -> createElement ('DATE', date ('d-m-Y H:i:s'));
$aElem[] = $this -> oXMLDOC -> createElement ('TYPE', $sType);
$sErrStr = utf8_encode ($sErrStr);
$aElem[] = $this -> oXMLDOC -> createElement ('PHP_MESSAGE', $sErrStr);
$aElem[] = $this -> oXMLDOC -> createElement ('FILE', $sErrFile);
$aElem[] = $this -> oXMLDOC -> createElement ('LINE', $iErrLine);
if (function_exists ('memory_get_usage')) {
$iMemory = @memory_get_usage ();
} else {
$iMemory = 'n/a';
}
$aElem[] = $this -> oXMLDOC -> createElement ('MEMORY', $iMemory);
$aElem[] = $this -> oXMLDOC -> createElement ('TRANSLATION', $aTempArr['TRANSLATION']);
$aElem[] = $this -> oXMLDOC -> createElement ('SUGGESTION', $aTempArr['SUGGESTION']);
$aElem[] = $this -> oXMLDOC -> createElement ('CONTEXT', $sVars);
$oSource = $this -> oXMLDOC -> createElement ('SOURCE');
$aSourceElem = array ();
foreach ($this -> getLine ($sErrFile, $iErrLine) as $iLine => $sLine) {
$sLine = utf8_encode ($sLine);
if ($iLine === ($iErrLine)) {
$aSourceElem[] = $this -> oXMLDOC -> createElement ('SOURCE_LINE_ERROR', ' /** ERROR AROUND THIS LINE => */ '.$sLine);
} else {
$aSourceElem[] = $this -> oXMLDOC -> createElement ('SOURCE_LINE', $sLine);
}
}
foreach ($aSourceElem as $oSourceElem) {
$oSource -> appendChild ($oSourceElem);
}
foreach ($aElem as $oElem) {
$oNewLog -> appendChild ($oElem);
}
$oNewLog -> appendChild ($oSource);
$this -> oCurrentNode = $oNewLog;
if (true === $this -> aOptions['REALTIME']) {
$this -> printMe ();
}
}
/**
* private function getLine ()
* method to get the lines around the detected error
* @Param (string) sErrFile : the file in which the error has been detected
* @Param (int) iErrLine : the line of the error
* @Return (array) aSource : array with each line
*/
private function getLine ($sErrFile, $iErrLine) {
$aSource = array ();
if (file_exists ($sErrFile)) {
$aLines = file ($sErrFile);
for ($i = $iErrLine - $this -> iNbLines; $i<= $iErrLine + $this -> iNbLines; $i ++) {
if (isset ($aLines[$i])) {
$aSource[$i] = $aLines[$i];
}
}
}
return $aSource;
}
/**
* public function loadXML ()
* loads an external error log
* @Param (string) sFile : the error log file to be loaded
*/
public function loadXML ($sFile) {
if (!file_exists ('logs/'.$sFile)) {
return false;
}
$this -> oXMLDOC -> load ('logs/'.$sFile);
}
/**
* public function showAll ()
* show the whole current xml log
*/
public function showAll () {
$xpath = new DOMXPath($this -> oXMLDOC);
$sQuery = '//ERROR';
$oNodeLists = $xpath -> query ($sQuery);
foreach ($oNodeLists as $oNodeList) {
$this -> oCurrentNode = $oNodeList;
$this -> printMe ();
}
}
/**
* public function showLog ()
* show the whole current log in a table, with stats (best used after odebugger::loadXML())
* @Return (string) sHtml : the generated HTML
*/
public function showLog () {
$sBaseHtml = file_get_contents ('templates/'.$this -> sTemplateHTMLLOG.'.dat');
$iStartPos = strpos ($sBaseHtml, '<!-- LINES HERE -->');
$sHtml = substr ($sBaseHtml, 0, $iStartPos);
$iEndPos = strpos ($sBaseHtml, '<!-- STATS -->');
$iLength = strlen ($sBaseHtml);
$sTempHtml = substr ($sBaseHtml, $iStartPos, - ($iLength - $iEndPos));
$sTempHtmlTotal = '';
$xpath = new DOMXPath($this -> oXMLDOC);
$sQuery = '//ERROR';
$oNodeLists = $xpath -> query ($sQuery);
foreach ($oNodeLists as $oNodeList) {
$this -> oCurrentNode = $oNodeList;
$sTempHtmlTotal .= $this -> printMeLog ($sTempHtml);
}
$sHtml .= $sTempHtmlTotal;
$sQuery = '//ERROR/TYPE';
$oNodeLists = $xpath -> query ($sQuery);
foreach ($oNodeLists as $oNodeList) {
$aTypes[] = $oNodeList -> nodeValue;
}
$sHtml .= substr ($sBaseHtml, $iEndPos, ($iLength - 1));
$aCountType = array_count_values ($aTypes);
$sCountType = '';
foreach ($aCountType as $kType => $vType) {
$sCountType .= $kType.' : '.$vType.'<br />';
}
$sVersion = @phpversion ();
$sHtml = str_replace ($this -> aIndex[100], $sCountType, $sHtml);
$sHtml = str_replace ($this -> aIndex[101], $sVersion , $sHtml);
return $sHtml;
}
/**
* private function printMe ()
* display a caught error
* @Return (string) sHtml : the generated HTML
*/
private function printMe () {
$sHtml = file_get_contents ('templates/'.$this -> sTemplateHTML.'.dat');
$nodeList = $this -> oCurrentNode -> childNodes;
$iId = $this -> oCurrentNode -> getAttribute ('id');
for ($i = 0; $i < $nodeList -> length; $i++) {
$sName = $nodeList -> item($i) -> nodeName;
if ($sName === 'SOURCE') {
$sourceNodeList = $nodeList -> item($i) -> childNodes;
$sValeur = '';
for ($j = 0; $j < $sourceNodeList -> length; $j++) {
$sValeur .= str_replace (array ('<?php', '?>', '<?'), '', $sourceNodeList -> item($j) -> nodeValue);
}
$sValeur = highlight_string ('<?php '."\r\n".$sValeur.'?>', true);
} else {
$sValeur = $nodeList -> item($i) -> nodeValue;
}
$sId = uniqid().'_'.$iId;
$aReplacement = array ($sName, $sValeur);
$sHtml = str_replace ($this -> aIndex[$i], $aReplacement, $sHtml);
$sHtml = str_replace ('{ID}', $sId, $sHtml);
}
echo $sHtml;
}
/**
* private function printMeLog ()
* display a caught error, used by odebugger::showLog()
* @Return (string) sHtml : the generated HTML
*/
private function printMeLog ($sHtml) {
$nodeList = $this -> oCurrentNode -> childNodes;
for ($i = 0; $i < $nodeList -> length; $i++) {
if ($nodeList -> item($i) -> nodeName === 'SOURCE') {
$sourceNodeList = $nodeList -> item($i) -> childNodes;
$sValeur = '';
for ($j = 0; $j < $sourceNodeList -> length; $j++) {
$sValeur .= str_replace (array ('<?php', '?>', '<?'), '', $sourceNodeList -> item($j) -> nodeValue);
}
$sValeur = highlight_string ('<?php '."\r\n".$sValeur. |
| |
