CErrorHandler

All Packages | Properties | Methods

Package	system.base
Inheritance	class CErrorHandler » CApplicationComponent » CComponent
Implements	IApplicationComponent
Since	1.0
Version	$Id: CErrorHandler.php 3540 2012-01-16 10:17:01Z mdomba $
Source Code	framework/base/CErrorHandler.php

CErrorHandler handles uncaught PHP errors and exceptions.

It displays these errors using appropriate views based on the nature of the error and the mode the application runs at. It also chooses the most preferred language for displaying the error.

CErrorHandler uses two sets of views:

development views, named as exception.php;
production views, named as error<StatusCode>.php;

where <StatusCode> stands for the HTTP error code (e.g. error500.php). Localized views are named similarly but located under a subdirectory whose name is the language code (e.g. zh_cn/error500.php).

Development views are displayed when the application is in debug mode (i.e. YII_DEBUG is defined as true). Detailed error information with source code are displayed in these views. Production views are meant to be shown to end-users and are used when the application is in production mode. For security reasons, they only display the error message without any sensitive information.

CErrorHandler looks for the view templates from the following locations in order:

themes/ThemeName/views/system: when a theme is active.
protected/views/system
framework/views

If the view is not found in a directory, it will be looked for in the next directory.

The property maxSourceLines can be changed to specify the number of source code lines to be displayed in development views.

CErrorHandler is a core application component that can be accessed via CApplication::getErrorHandler().

Public Properties

Hide inherited properties

Property	Type	Description	Defined By
adminInfo	string	the application administrator information (could be a name or email link).	CErrorHandler
behaviors	array	the behaviors that should be attached to this component.	CApplicationComponent
discardOutput	boolean	whether to discard any existing page output before error display.	CErrorHandler
error	array	Returns the details about the error that is currently being handled.	CErrorHandler
errorAction	string	the route (eg 'site/error') to the controller action that will be used to display external errors.	CErrorHandler
isInitialized	boolean	Checks if this application component bas been initialized.	CApplicationComponent
maxSourceLines	integer	maximum number of source code lines to be displayed.	CErrorHandler
maxTraceSourceLines	integer	maximum number of trace source code lines to be displayed.	CErrorHandler

Protected Properties

Hide inherited properties

Property	Type	Description	Defined By
versionInfo	string	Returns server version information.	CErrorHandler

Public Methods

Hide inherited methods

Method	Description	Defined By
__call()	Calls the named method which is not a class method.	CComponent
__get()	Returns a property value, an event handler list or a behavior based on its name.	CComponent
__isset()	Checks if a property value is null.	CComponent
__set()	Sets value of a component property.	CComponent
__unset()	Sets a component property to be null.	CComponent
asa()	Returns the named behavior object.	CComponent
attachBehavior()	Attaches a behavior to this component.	CComponent
attachBehaviors()	Attaches a list of behaviors to the component.	CComponent
attachEventHandler()	Attaches an event handler to an event.	CComponent
canGetProperty()	Determines whether a property can be read.	CComponent
canSetProperty()	Determines whether a property can be set.	CComponent
detachBehavior()	Detaches a behavior from the component.	CComponent
detachBehaviors()	Detaches all behaviors from the component.	CComponent
detachEventHandler()	Detaches an existing event handler.	CComponent
disableBehavior()	Disables an attached behavior.	CComponent
disableBehaviors()	Disables all behaviors attached to this component.	CComponent
enableBehavior()	Enables an attached behavior.	CComponent
enableBehaviors()	Enables all behaviors attached to this component.	CComponent
evaluateExpression()	Evaluates a PHP expression or callback under the context of this component.	CComponent
getError()	Returns the details about the error that is currently being handled.	CErrorHandler
getEventHandlers()	Returns the list of attached event handlers for an event.	CComponent
getIsInitialized()	Checks if this application component bas been initialized.	CApplicationComponent
handle()	Handles the exception/error event.	CErrorHandler
hasEvent()	Determines whether an event is defined.	CComponent
hasEventHandler()	Checks whether the named event has attached handlers.	CComponent
hasProperty()	Determines whether a property is defined.	CComponent
init()	Initializes the application component.	CApplicationComponent
raiseEvent()	Raises an event.	CComponent

Protected Methods

Hide inherited methods

Method	Description	Defined By
argumentsToString()	Converts arguments array to its string representation	CErrorHandler
getExactTrace()	Returns the exact trace where the problem occurs.	CErrorHandler
getVersionInfo()	Returns server version information.	CErrorHandler
getViewFile()	Determines which view file should be used.	CErrorHandler
getViewFileInternal()	Looks for the view under the specified directory.	CErrorHandler
handleError()	Handles the PHP error.	CErrorHandler
handleException()	Handles the exception.	CErrorHandler
isAjaxRequest()	whether the current request is an AJAX (XMLHttpRequest) request.	CErrorHandler
isCoreCode()	Returns a value indicating whether the call stack is from application code.	CErrorHandler
render()	Renders the view.	CErrorHandler
renderSourceCode()	Renders the source code around the error line.	CErrorHandler

Property Details

adminInfo property

public string $adminInfo;

the application administrator information (could be a name or email link). It is displayed in error pages to end users. Defaults to 'the webmaster'.

discardOutput property

public boolean $discardOutput;

whether to discard any existing page output before error display. Defaults to true.

error property read-only

public array getError()

Returns the details about the error that is currently being handled. The error is returned in terms of an array, with the following information:

code - the HTTP status code (e.g. 403, 500)
type - the error type (e.g. 'CHttpException', 'PHP Error')
message - the error message
file - the name of the PHP script file where the error occurs
line - the line number of the code where the error occurs
trace - the call stack of the error
source - the context source code where the error occurs

errorAction property

public string $errorAction;

the route (eg 'site/error') to the controller action that will be used to display external errors. Inside the action, it can retrieve the error information by Yii::app()->errorHandler->error. This property defaults to null, meaning CErrorHandler will handle the error display.

maxSourceLines property

public integer $maxSourceLines;

maximum number of source code lines to be displayed. Defaults to 25.

maxTraceSourceLines property (available since v1.1.6)

public integer $maxTraceSourceLines;

maximum number of trace source code lines to be displayed. Defaults to 10.

versionInfo property read-only

protected string getVersionInfo()

Returns server version information. If the application is in production mode, empty string is returned.

Method Details

argumentsToString() method

protected string argumentsToString(array $args)
$args	array	arguments array to be converted
{return}	string	string representation of the arguments array

Source Code: framework/base/CErrorHandler.php#392 (show)


protected function argumentsToString($args)
{
    $count=0;

    $isAssoc=$args!==array_values($args);

    foreach($args as $key => $value)
    {
        $count++;
        if($count>=5)
        {
            if($count>5)
                unset($args[$key]);
            else
                $args[$key]='...';
            continue;
        }

        if(is_object($value))
            $args[$key] = get_class($value);
        else if(is_bool($value))
            $args[$key] = $value ? 'true' : 'false';
        else if(is_string($value))
        {
            if(strlen($value)>64)
                $args[$key] = '"'.substr($value,0,64).'..."';
            else
                $args[$key] = '"'.$value.'"';
        }
        else if(is_array($value))
            $args[$key] = 'array('.$this->argumentsToString($value).')';
        else if($value===null)
            $args[$key] = 'null';
        else if(is_resource($value))
            $args[$key] = 'resource';

        if(is_string($key))
        {
            $args[$key] = '"'.$key.'" => '.$args[$key];
        }
        else if($isAssoc)
        {
            $args[$key] = $key.' => '.$args[$key];
        }
    }
    $out = implode(", ", $args);

    return $out;
}

Converts arguments array to its string representation

getError() method

public array getError()
{return}	array	the error details. Null if there is no error.

Source Code: framework/base/CErrorHandler.php#127 (show)


public function getError()
{
    return $this->_error;
}

Returns the details about the error that is currently being handled. The error is returned in terms of an array, with the following information:

code - the HTTP status code (e.g. 403, 500)
type - the error type (e.g. 'CHttpException', 'PHP Error')
message - the error message
file - the name of the PHP script file where the error occurs
line - the line number of the code where the error occurs
trace - the call stack of the error
source - the context source code where the error occurs

getExactTrace() method

protected array getExactTrace(Exception $exception)
$exception	Exception	the uncaught exception
{return}	array	the exact trace where the problem occurs

Source Code: framework/base/CErrorHandler.php#288 (show)


protected function getExactTrace($exception)
{
    $traces=$exception->getTrace();

    foreach($traces as $trace)
    {
        // property access exception
        if(isset($trace['function']) && ($trace['function']==='__get' || $trace['function']==='__set'))
            return $trace;
    }
    return null;
}

Returns the exact trace where the problem occurs.

getVersionInfo() method

protected string getVersionInfo()
{return}	string	server version information. Empty if in production mode.

Source Code: framework/base/CErrorHandler.php#373 (show)


protected function getVersionInfo()
{
    if(YII_DEBUG)
    {
        $version='<a href="http://www.yiiframework.com/">Yii Framework</a>/'.Yii::getVersion();
        if(isset($_SERVER['SERVER_SOFTWARE']))
            $version=$_SERVER['SERVER_SOFTWARE'].' '.$version;
    }
    else
        $version='';
    return $version;
}

Returns server version information. If the application is in production mode, empty string is returned.

getViewFile() method

protected string getViewFile(string $view, integer $code)
$view	string	view name (either 'exception' or 'error')
$code	integer	HTTP status code
{return}	string	view file path

Source Code: framework/base/CErrorHandler.php#327 (show)


protected function getViewFile($view,$code)
{
    $viewPaths=array(
        Yii::app()->getTheme()===null ? null :  Yii::app()->getTheme()->getSystemViewPath(),
        Yii::app() instanceof CWebApplication ? Yii::app()->getSystemViewPath() : null,
        YII_PATH.DIRECTORY_SEPARATOR.'views',
    );

    foreach($viewPaths as $i=>$viewPath)
    {
        if($viewPath!==null)
        {
             $viewFile=$this->getViewFileInternal($viewPath,$view,$code,$i===2?'en_us':null);
             if(is_file($viewFile))
                  return $viewFile;
        }
    }
}

Determines which view file should be used.

getViewFileInternal() method

protected string getViewFileInternal(string $viewPath, string $view, integer $code, string $srcLanguage=NULL)
$viewPath	string	the directory containing the views
$view	string	view name (either 'exception' or 'error')
$code	integer	HTTP status code
$srcLanguage	string	the language that the view file is in
{return}	string	view file path

Source Code: framework/base/CErrorHandler.php#354 (show)


protected function getViewFileInternal($viewPath,$view,$code,$srcLanguage=null)
{
    $app=Yii::app();
    if($view==='error')
    {
        $viewFile=$app->findLocalizedFile($viewPath.DIRECTORY_SEPARATOR."error{$code}.php",$srcLanguage);
        if(!is_file($viewFile))
            $viewFile=$app->findLocalizedFile($viewPath.DIRECTORY_SEPARATOR.'error.php',$srcLanguage);
    }
    else
        $viewFile=$viewPath.DIRECTORY_SEPARATOR."exception.php";
    return $viewFile;
}

Looks for the view under the specified directory.

handle() method

public void handle(CEvent $event)
$event	CEvent	the event containing the exception/error information

Source Code: framework/base/CErrorHandler.php#93 (show)


public function handle($event)
{
    // set event as handled to prevent it from being handled by other event handlers
    $event->handled=true;

    if($this->discardOutput)
    {
        // the following manual level counting is to deal with zlib.output_compression set to On
        for($level=ob_get_level();$level>0;--$level)
        {
            @ob_end_clean();
        }
    }

    if($event instanceof CExceptionEvent)
        $this->handleException($event->exception);
    else // CErrorEvent
        $this->handleError($event);
}

Handles the exception/error event. This method is invoked by the application whenever it captures an exception or PHP error.

handleError() method

protected void handleError(CErrorEvent $event)
$event	CErrorEvent	the PHP error event

Source Code: framework/base/CErrorHandler.php#200 (show)


protected function handleError($event)
{
    $trace=debug_backtrace();
    // skip the first 3 stacks as they do not tell the error position
    if(count($trace)>3)
        $trace=array_slice($trace,3);
    $traceString='';
    foreach($trace as $i=>$t)
    {
        if(!isset($t['file']))
            $trace[$i]['file']='unknown';

        if(!isset($t['line']))
            $trace[$i]['line']=0;

        if(!isset($t['function']))
            $trace[$i]['function']='unknown';

        $traceString.="#$i {$trace[$i]['file']}({$trace[$i]['line']}): ";
        if(isset($t['object']) && is_object($t['object']))
            $traceString.=get_class($t['object']).'->';
        $traceString.="{$trace[$i]['function']}()\n";

        unset($trace[$i]['object']);
    }

    $app=Yii::app();
    if($app instanceof CWebApplication)
    {
        switch($event->code)
        {
            case E_WARNING:
                $type = 'PHP warning';
                break;
            case E_NOTICE:
                $type = 'PHP notice';
                break;
            case E_USER_ERROR:
                $type = 'User error';
                break;
            case E_USER_WARNING:
                $type = 'User warning';
                break;
            case E_USER_NOTICE:
                $type = 'User notice';
                break;
            case E_RECOVERABLE_ERROR:
                $type = 'Recoverable error';
                break;
            default:
                $type = 'PHP error';
        }
        $this->_error=$data=array(
            'code'=>500,
            'type'=>$type,
            'message'=>$event->message,
            'file'=>$event->file,
            'line'=>$event->line,
            'trace'=>$traceString,
            'traces'=>$trace,
        );
        if(!headers_sent())
            header("HTTP/1.0 500 PHP Error");
        if($this->isAjaxRequest())
            $app->displayError($event->code,$event->message,$event->file,$event->line);
        else if(YII_DEBUG)
            $this->render('exception',$data);
        else
            $this->render('error',$data);
    }
    else
        $app->displayError($event->code,$event->message,$event->file,$event->line);
}

Handles the PHP error.

handleException() method

protected void handleException(Exception $exception)
$exception	Exception	the exception captured

Source Code: framework/base/CErrorHandler.php#136 (show)


protected function handleException($exception)
{
    $app=Yii::app();
    if($app instanceof CWebApplication)
    {
        if(($trace=$this->getExactTrace($exception))===null)
        {
            $fileName=$exception->getFile();
            $errorLine=$exception->getLine();
        }
        else
        {
            $fileName=$trace['file'];
            $errorLine=$trace['line'];
        }

        $trace = $exception->getTrace();

        foreach($trace as $i=>$t)
        {
            if(!isset($t['file']))
                $trace[$i]['file']='unknown';

            if(!isset($t['line']))
                $trace[$i]['line']=0;

            if(!isset($t['function']))
                $trace[$i]['function']='unknown';

            unset($trace[$i]['object']);
        }

        $this->_error=$data=array(
            'code'=>($exception instanceof CHttpException)?$exception->statusCode:500,
            'type'=>get_class($exception),
            'errorCode'=>$exception->getCode(),
            'message'=>$exception->getMessage(),
            'file'=>$fileName,
            'line'=>$errorLine,
            'trace'=>$exception->getTraceAsString(),
            'traces'=>$trace,
        );

        if(!headers_sent())
            header("HTTP/1.0 {$data['code']} ".get_class($exception));

        if($exception instanceof CHttpException || !YII_DEBUG)
            $this->render('error',$data);
        else
        {
            if($this->isAjaxRequest())
                $app->displayException($exception);
            else
                $this->render('exception',$data);
        }
    }
    else
        $app->displayException($exception);
}

Handles the exception.

isAjaxRequest() method

protected boolean isAjaxRequest()
{return}	boolean	whether the current request is an AJAX request.

Source Code: framework/base/CErrorHandler.php#278 (show)


protected function isAjaxRequest()
{
    return isset($_SERVER['HTTP_X_REQUESTED_WITH']) && $_SERVER['HTTP_X_REQUESTED_WITH']==='XMLHttpRequest';
}

whether the current request is an AJAX (XMLHttpRequest) request.

isCoreCode() method

protected boolean isCoreCode(array $trace)
$trace	array	the trace data
{return}	boolean	whether the call stack is from application code.

Source Code: framework/base/CErrorHandler.php#447 (show)


protected function isCoreCode($trace)
{
    if(isset($trace['file']))
    {
        $systemPath=realpath(dirname(__FILE__).'/..');
        return $trace['file']==='unknown' || strpos(realpath($trace['file']),$systemPath.DIRECTORY_SEPARATOR)===0;
    }
    return false;
}

Returns a value indicating whether the call stack is from application code.

render() method

protected void render(string $view, array $data)
$view	string	the view name (file name without extension). See getViewFile for how a view file is located given its name.
$data	array	data to be passed to the view

Source Code: framework/base/CErrorHandler.php#307 (show)


protected function render($view,$data)
{
    if($view==='error' && $this->errorAction!==null)
        Yii::app()->runController($this->errorAction);
    else
    {
        // additional information to be passed to view
        $data['version']=$this->getVersionInfo();
        $data['time']=time();
        $data['admin']=$this->adminInfo;
        include($this->getViewFile($view,$data['code']));
    }
}

Renders the view.

renderSourceCode() method

protected string renderSourceCode(string $file, integer $errorLine, integer $maxLines)
$file	string	source file path
$errorLine	integer	the error line number
$maxLines	integer	maximum number of lines to display
{return}	string	the rendering result

Source Code: framework/base/CErrorHandler.php#464 (show)


protected function renderSourceCode($file,$errorLine,$maxLines)
{
    $errorLine--;    // adjust line number to 0-based from 1-based
    if($errorLine<0 || ($lines=@file($file))===false || ($lineCount=count($lines))<=$errorLine)
        return '';

    $halfLines=(int)($maxLines/2);
    $beginLine=$errorLine-$halfLines>0 ? $errorLine-$halfLines:0;
    $endLine=$errorLine+$halfLines<$lineCount?$errorLine+$halfLines:$lineCount-1;
    $lineNumberWidth=strlen($endLine+1);

    $output='';
    for($i=$beginLine;$i<=$endLine;++$i)
    {
        $isErrorLine = $i===$errorLine;
        $code=sprintf("<span class=\"ln".($isErrorLine?' error-ln':'')."\">%0{$lineNumberWidth}d</span> %s",$i+1,CHtml::encode(str_replace("\t",'    ',$lines[$i])));
        if(!$isErrorLine)
            $output.=$code;
        else
            $output.='<span class="error">'.$code.'</span>';
    }
    return '<div class="code"><pre>'.$output.'</pre></div>';
}

Renders the source code around the error line.