diff options
Diffstat (limited to 'framework/Exceptions/TErrorHandler.php')
| -rw-r--r-- | framework/Exceptions/TErrorHandler.php | 102 |
1 files changed, 97 insertions, 5 deletions
diff --git a/framework/Exceptions/TErrorHandler.php b/framework/Exceptions/TErrorHandler.php index 52ed9935..d053619f 100644 --- a/framework/Exceptions/TErrorHandler.php +++ b/framework/Exceptions/TErrorHandler.php @@ -1,8 +1,63 @@ <?php
+/**
+ * TErrorHandler class file
+ *
+ * @author Qiang Xue <qiang.xue@gmail.com>
+ * @link http://www.pradosoft.com/
+ * @copyright Copyright © 2005 PradoSoft
+ * @license http://www.pradosoft.com/license/
+ * @version $Revision: $ $Date: $
+ * @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
+ * <b>error[StatusCode][-LanguageCode].html</b>, and for the latter it is
+ * <b>exception[-LanguageCode].html</b>, 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 <b>error.html</b> and <b>exception.html</b> are default ones
+ * that are used if no other appropriate templates are available.
+ * Note, these templates are not Prado control templates. They are simply
+ * templates with keywords (e.g. %%ErrorMessage%%, %%Version%%)
+ * to be replaced with 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
+ * <module id="error" type="TErrorHandler" ErrorTemplatePath="System.Exceptions" />
+ *
+ * @author Qiang Xue <qiang.xue@gmail.com>
+ * @version $Revision: $ $Date: $
+ * @package System.Exceptions
+ * @since 3.0
+ */
class TErrorHandler extends TComponent implements IModule
{
+ /**
+ * error template file basename
+ */
const ERROR_FILE_NAME='error';
+ /**
+ * exception template file basename
+ */
const EXCEPTION_FILE_NAME='exception';
/**
@@ -52,6 +107,12 @@ class TErrorHandler extends TComponent implements IModule 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($this->_templatePath))!==null && is_dir($templatePath))
@@ -60,15 +121,25 @@ class TErrorHandler extends TComponent implements IModule throw new TConfigurationException('errorhandler_errortemplatepath_invalid',$value);
}
+ /**
+ * Handles PHP user errors and exceptions.
+ * This is the event handler responding to the <b>Error</b> 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,
- // otherwise because errors occured in error handler
- // will not be handled properly.
+ // because within error and exception handlers, new errors and exceptions
+ // cannot be handled properly by PHP
restore_error_handler();
restore_exception_handler();
- if($handling) // ensure that we do not enter infinite loop of error handling
+ // ensure that we do not enter infinite loop of error handling
+ if($handling)
$this->handleRecursiveError($param);
else
{
@@ -85,6 +156,13 @@ class TErrorHandler extends TComponent implements IModule exit(1);
}
+ /**
+ * Displays error to the client user.
+ * THttpException and errors happened when the application is in <b>Debug</b>
+ * 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))
@@ -122,6 +200,13 @@ class TErrorHandler extends TComponent implements IModule echo str_replace($fields,$values,$content);
}
+ /**
+ * Handles error occurs during error handling (called recursive error).
+ * THttpException and errors happened when the application is in <b>Debug</b>
+ * 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(Prado::getApplication()->getMode()==='Debug')
@@ -138,6 +223,13 @@ class TErrorHandler extends TComponent implements IModule }
}
+ /**
+ * 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 <b>Debug</b> mode.
+ * @param Exception exception instance
+ */
protected function displayException($exception)
{
$lines=file($exception->getFile());
@@ -174,9 +266,9 @@ class TErrorHandler extends TComponent implements IModule strftime('%Y-%m-%d %H:%m',time())
);
$lang=Prado::getPreferredLanguage();
- $exceptionFile=dirname(__FILE__).'/'.self::EXCEPTION_FILE_NAME.'-'.$lang.'.html';
+ $exceptionFile=$this->_templatePath.'/'.self::EXCEPTION_FILE_NAME.'-'.$lang.'.html';
if(!is_file($exceptionFile))
- $exceptionFile=dirname(__FILE__).'/'.self::EXCEPTION_FILE_NAME.'.html';
+ $exceptionFile=$this->_templatePath.'/'.self::EXCEPTION_FILE_NAME.'.html';
if(($content=@file_get_contents($exceptionFile))===false)
die("Unable to open exception template file '$exceptionFile'.");
echo str_replace($fields,$values,$content);
|