* @link http://www.pradosoft.com/ * @copyright Copyright © 2005 PradoSoft * @license http://www.pradosoft.com/license/ * @version $Id$ * @package System.Exceptions */ /** * TErrorHandler class * * TErrorHandler handles all PHP user errors and exceptions generated during * servicing user requests. It displays these errors using different templates * and if possible, using languages preferred by the client user. * Note, PHP parsing errors cannot be caught and handled by TErrorHandler. * * The templates used to format the error output are stored under System.Exceptions. * You may choose to use your own templates, should you not like the templates * provided by Prado. Simply set {@link setErrorTemplatePath ErrorTemplatePath} * to the path (in namespace format) storing your own templates. * * There are two sets of templates, one for errors to be displayed to client users * (called external errors), one for errors to be displayed to system developers * (called internal errors). The template file name for the former is * error[StatusCode][-LanguageCode].html, and for the latter it is * exception[-LanguageCode].html, where StatusCode refers to response status * code (e.g. 404, 500) specified when {@link THttpException} is thrown, * and LanguageCode is the client user preferred language code (e.g. en, zh, de). * The templates error.html and exception.html are default ones * that are used if no other appropriate templates are available. * Note, these templates are not Prado control templates. They are simply * html files with keywords (e.g. %%ErrorMessage%%, %%Version%%) * to be replaced with the corresponding information. * * By default, TErrorHandler is registered with {@link TApplication} as the * error handler module. It can be accessed via {@link TApplication::getErrorHandler()}. * You seldom need to deal with the error handler directly. It is mainly used * by the application object to handle errors. * * TErrorHandler may be configured in application configuration file as follows * * * @author Qiang Xue * @version $Id$ * @package System.Exceptions * @since 3.0 */ class TErrorHandler extends TModule { /** * error template file basename */ const ERROR_FILE_NAME='error'; /** * exception template file basename */ const EXCEPTION_FILE_NAME='exception'; /** * number of lines before and after the error line to be displayed in case of an exception */ const SOURCE_LINES=12; /** * @var string error template directory */ private $_templatePath=null; /** * Initializes the module. * This method is required by IModule and is invoked by application. * @param TXmlElement module configuration */ public function init($config) { $this->getApplication()->setErrorHandler($this); if($this->_templatePath===null) $this->_templatePath=Prado::getFrameworkPath().'/Exceptions/templates'; } /** * @return string the directory containing error template files. */ public function getErrorTemplatePath() { return $this->_templatePath; } /** * Sets the path storing all error and exception template files. * The path must be in namespace format, such as System.Exceptions (which is the default). * @param string template path in namespace format * @throws TConfigurationException if the template path is invalid */ public function setErrorTemplatePath($value) { if(($templatePath=Prado::getPathOfNamespace($value))!==null && is_dir($templatePath)) $this->_templatePath=$templatePath; else throw new TConfigurationException('errorhandler_errortemplatepath_invalid',$value); } /** * Handles PHP user errors and exceptions. * This is the event handler responding to the Error event * raised in {@link TApplication}. * The method mainly uses appropriate template to display the error/exception. * It terminates the application immediately after the error is displayed. * @param mixed sender of the event * @param mixed event parameter (if the event is raised by TApplication, it refers to the exception instance) */ public function handleError($sender,$param) { static $handling=false; // We need to restore error and exception handlers, // because within error and exception handlers, new errors and exceptions // cannot be handled properly by PHP restore_error_handler(); restore_exception_handler(); // ensure that we do not enter infinite loop of error handling if($handling) $this->handleRecursiveError($param); else { $handling=true; if(($response=$this->getResponse())!==null) $response->clear(); if(!headers_sent()) header('Content-Type: text/html; charset=UTF-8'); if($param instanceof THttpException) $this->handleExternalError($param->getStatusCode(),$param); else if($this->getApplication()->getMode()===TApplicationMode::Debug) $this->displayException($param); else $this->handleExternalError(500,$param); } } /** * Displays error to the client user. * THttpException and errors happened when the application is in Debug * mode will be displayed to the client user. * @param integer response status code * @param Exception exception instance */ protected function handleExternalError($statusCode,$exception) { if(!($exception instanceof THttpException)) error_log($exception->__toString()); $content=$this->getErrorTemplate($statusCode,$exception); $serverAdmin=isset($_SERVER['SERVER_ADMIN'])?$_SERVER['SERVER_ADMIN']:''; if($this->getApplication()->getMode()===TApplicationMode::Debug) $version=$_SERVER['SERVER_SOFTWARE'].' PRADO/'.Prado::getVersion(); else $version=''; $tokens=array( '%%StatusCode%%' => "$statusCode", '%%ErrorMessage%%' => htmlspecialchars($exception->getMessage()), '%%ServerAdmin%%' => $serverAdmin, '%%Version%%' => $version, '%%Time%%' => @strftime('%Y-%m-%d %H:%M',time()) ); echo strtr($content,$tokens); } /** * Handles error occurs during error handling (called recursive error). * THttpException and errors happened when the application is in Debug * mode will be displayed to the client user. * Error is displayed without using existing template to prevent further errors. * @param Exception exception instance */ protected function handleRecursiveError($exception) { if($this->getApplication()->getMode()===TApplicationMode::Debug) { echo "Recursive Error\n"; echo "

Recursive Error

\n"; echo "
".$exception->__toString()."
\n"; echo ""; } else { error_log("Error happened while processing an existing error:\n".$exception->__toString()); header('HTTP/1.0 500 Internal Error'); } } /** * Displays exception information. * Exceptions are displayed with rich context information, including * the call stack and the context source code. * This method is only invoked when application is in Debug mode. * @param Exception exception instance */ protected function displayException($exception) { if(php_sapi_name()==='cli') { echo $exception->getMessage()."\n"; echo $exception->getTraceAsString(); return; } if($exception instanceof TTemplateException) { $fileName=$exception->getTemplateFile(); $lines=empty($fileName)?explode("\n",$exception->getTemplateSource()):@file($fileName); $source=$this->getSourceCode($lines,$exception->getLineNumber()); if($fileName==='') $fileName='---embedded template---'; $errorLine=$exception->getLineNumber(); } else { if(($trace=$this->getExactTrace($exception))!==null) { $fileName=$trace['file']; $errorLine=$trace['line']; } else { $fileName=$exception->getFile(); $errorLine=$exception->getLine(); } $source=$this->getSourceCode(@file($fileName),$errorLine); } if($this->getApplication()->getMode()===TApplicationMode::Debug) $version=$_SERVER['SERVER_SOFTWARE'].' PRADO/'.Prado::getVersion(); else $version=''; $tokens=array( '%%ErrorType%%' => get_class($exception), '%%ErrorMessage%%' => $this->addLink(htmlspecialchars($exception->getMessage())), '%%SourceFile%%' => htmlspecialchars($fileName).' ('.$errorLine.')', '%%SourceCode%%' => $source, '%%StackTrace%%' => htmlspecialchars($exception->getTraceAsString()), '%%Version%%' => $version, '%%Time%%' => @strftime('%Y-%m-%d %H:%M',time()) ); $content=$this->getExceptionTemplate($exception); echo strtr($content,$tokens); } /** * Retrieves the template used for displaying internal exceptions. * Internal exceptions will be displayed with source code causing the exception. * This occurs when the application is in debug mode. * @param Exception the exception to be displayed * @return string the template content */ protected function getExceptionTemplate($exception) { $lang=Prado::getPreferredLanguage(); $exceptionFile=Prado::getFrameworkPath().'/Exceptions/templates/'.self::EXCEPTION_FILE_NAME.'-'.$lang.'.html'; if(!is_file($exceptionFile)) $exceptionFile=Prado::getFrameworkPath().'/Exceptions/templates/'.self::EXCEPTION_FILE_NAME.'.html'; if(($content=@file_get_contents($exceptionFile))===false) die("Unable to open exception template file '$exceptionFile'."); return $content; } /** * Retrieves the template used for displaying external exceptions. * External exceptions are those displayed to end-users. They do not contain * error source code. Therefore, you might want to override this method * to provide your own error template for displaying certain external exceptions. * The following tokens in the template will be replaced with corresponding content: * %%StatusCode%% : the status code of the exception * %%ErrorMessage%% : the error message (HTML encoded). * %%ServerAdmin%% : the server admin information (retrieved from Web server configuration) * %%Version%% : the version information of the Web server. * %%Time%% : the time the exception occurs at * * @param integer status code (such as 404, 500, etc.) * @param Exception the exception to be displayed * @return string the template content */ protected function getErrorTemplate($statusCode,$exception) { $base=$this->getErrorTemplatePath().DIRECTORY_SEPARATOR.self::ERROR_FILE_NAME; $lang=Prado::getPreferredLanguage(); if(is_file("$base$statusCode-$lang.html")) $errorFile="$base$statusCode-$lang.html"; else if(is_file("$base$statusCode.html")) $errorFile="$base$statusCode.html"; else if(is_file("$base-$lang.html")) $errorFile="$base-$lang.html"; else $errorFile="$base.html"; if(($content=@file_get_contents($errorFile))===false) die("Unable to open error template file '$errorFile'."); return $content; } private function getExactTrace($exception) { $trace=$exception->getTrace(); $result=null; // if PHP exception, we want to show the 2nd stack level context // because the 1st stack level is of little use (it's in error handler) if($exception instanceof TPhpErrorException) $result=isset($trace[0]['file'])?$trace[0]:$trace[1]; else if($exception instanceof TInvalidOperationException) { // in case of getter or setter error, find out the exact file and row if(($result=$this->getPropertyAccessTrace($trace,'__get'))===null) $result=$this->getPropertyAccessTrace($trace,'__set'); } if($result!==null && strpos($result['file'],': eval()\'d code')!==false) return null; return $result; } private function getPropertyAccessTrace($trace,$pattern) { $result=null; foreach($trace as $t) { if(isset($t['function']) && $t['function']===$pattern) $result=$t; else break; } return $result; } private function getSourceCode($lines,$errorLine) { $beginLine=$errorLine-self::SOURCE_LINES>=0?$errorLine-self::SOURCE_LINES:0; $endLine=$errorLine+self::SOURCE_LINES<=count($lines)?$errorLine+self::SOURCE_LINES:count($lines); $source=''; for($i=$beginLine;$i<$endLine;++$i) { if($i===$errorLine-1) { $line=htmlspecialchars(sprintf("%04d: %s",$i+1,str_replace("\t",' ',$lines[$i]))); $source.="
".$line."
"; } else $source.=htmlspecialchars(sprintf("%04d: %s",$i+1,str_replace("\t",' ',$lines[$i]))); } return $source; } private function addLink($message) { $baseUrl='http://www.pradosoft.com/docs/classdoc'; return preg_replace('/\b(T[A-Z]\w+)\b/',"\${1}",$message); } } ?>