Yii源码阅读笔记 - 错误/异常处理

概述

PHP区分“错误”（Error）和“异常”（Exception）。“错误”通常是由PHP内部函数抛出，表示运行时问题，当然也可以通过函数trigger_error或user_error抛出一个用户级别的error/warning/notice信息。但在引入面向对象之后，相比使用trigger_error抛出错误，使用throw抛出异常更常用。

对于“错误”，PHP允许配置报告哪些级别/类型错误、是否（向用户）展示错误、是否对错误记录日志、错误日志记到哪，分别对应php.ini中的配置项：error_reporting、display_errors、log_errors、error_log。详细信息见这里。

对于应用程序内层调用抛出的“异常”，一般可以在外层中使用try...catch来捕获并自定义处理过程。但对于“错误”（PHP运行时抛出或者应用程序使用trigger_error抛出的）或者对于-无法使用try...catch来捕获可能的异常/为了做到即使忘记捕获的异常也能得到自定义处理-的情况，该怎么办？对此，PHP提供了函数set_error_handler和set_exception_handler来注册错误/异常自定义处理过程。如果在程序的执行流中先后多次调用了set_error_handler或set_exception_handler，后一次注册的处理过程会覆盖前一次的，但可以通过函数restore_error_handler或restore_exception_handler来恢复前一次注册的异常处理过程。

之所以写这篇文章，是因为最近在工作中犯了一个低级错误：应用程序中有个API对于不合法的请求参数直接抛出异常（throw new Exception("xxx")），却忘了try...catch捕捉，导致异常被Yii框架（我们的应用基于Yii开发）通过set_exception_handler注册的方法处理 - 响应500，之后这个API被一个扫描器拼命扫，导致出现很多500响应，触发了告警。

分析

我们来看看Yii框架在哪个地方注册错误/异常处理过程？处理过程是什么样的？

Yii框架在请求处理初始化过程中，在CApplication类（见文件base/CApplication.php）的构造方法中调用了：

<?php
$this->initSystemHandlers();

initSystemHandlers的实现如下：

<?php
/**
 * Initializes the class autoloader and error handlers.
 */
protected function initSystemHandlers()
{
    // 注：如果不想使用Yii框架注册的handleException，可以在初始化应用实例之前，定义常量YII_ENABLE_EXCEPTION_HANDLER值为false
    if(YII_ENABLE_EXCEPTION_HANDLER)
        set_exception_handler(array($this,'handleException'));
    // 注：YII_ENABLE_ERROR_HANDLER也是如此
    if(YII_ENABLE_ERROR_HANDLER)
        set_error_handler(array($this,'handleError'),error_reporting());
}

其中注册的方法handleException和handleError实现分别如下：

<?php
public function handleException($exception)
{
    // disable error capturing to avoid recursive errors
    // 这句注释是啥意思？
    restore_error_handler();
    restore_exception_handler();

    // 生成并记录日志信息
    $category='exception.'.get_class($exception);
    if($exception instanceof CHttpException)
        $category.='.'.$exception->statusCode;
    // php <5.2 doesn't support string conversion auto-magically
    $message=$exception->__toString();
    if(isset($_SERVER['REQUEST_URI']))
        $message.="\nREQUEST_URI=".$_SERVER['REQUEST_URI'];
    if(isset($_SERVER['HTTP_REFERER']))
        $message.="\nHTTP_REFERER=".$_SERVER['HTTP_REFERER'];
    $message.="\n---";
    Yii::log($message,CLogger::LEVEL_ERROR,$category);

    try
    {
        // 将异常封装成事件，并触发事件，从而触发监听该事件的处理过程
        $event=new CExceptionEvent($this,$exception);
        $this->onException($event);
        // 如果事件并没有被处理（即没有监听该事件的处理过程）或者所有处理过程都没有将事件的handled属性置为true，则还得自己处理一下
        if(!$event->handled)
        {
            // try an error handler
            if(($handler=$this->getErrorHandler())!==null)
                $handler->handle($event);
            else
                $this->displayException($exception);
        }
    }
    catch(Exception $e)
    {
        $this->displayException($e);
    }

    try
    {
        // 尝试触发onEndRequest事件
        $this->end(1);
    }
    catch(Exception $e)
    {
        // use the most primitive way to log error
        $msg = get_class($e).': '.$e->getMessage().' ('.$e->getFile().':'.$e->getLine().")\n";
        $msg .= $e->getTraceAsString()."\n";
        $msg .= "Previous exception:\n";
        $msg .= get_class($exception).': '.$exception->getMessage().' ('.$exception->getFile().':'.$exception->getLine().")\n";
        $msg .= $exception->getTraceAsString()."\n";
        $msg .= '$_SERVER='.var_export($_SERVER,true);
        error_log($msg);
        exit(1);
    }
}

<?php
public function handleError($code,$message,$file,$line)
{
    if($code & error_reporting())
    {
        // disable error capturing to avoid recursive errors
        restore_error_handler();
        restore_exception_handler();

        // 生成并记录日志信息
        $log="$message ($file:$line)\nStack trace:\n";

        // debug_backtrace() 产生一条 PHP 的回溯跟踪
        $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);
        foreach($trace as $i=>$t)
        {
            if(!isset($t['file']))
                $t['file']='unknown';
            if(!isset($t['line']))
                $t['line']=0;
            if(!isset($t['function']))
                $t['function']='unknown';
            $log.="#$i {$t['file']}({$t['line']}): ";
            if(isset($t['object']) && is_object($t['object']))
                $log.=get_class($t['object']).'->';
            $log.="{$t['function']}()\n";
        }
        if(isset($_SERVER['REQUEST_URI']))
            $log.='REQUEST_URI='.$_SERVER['REQUEST_URI'];
        Yii::log($log,CLogger::LEVEL_ERROR,'php');

        try
        {
            // 将错误封装成事件，并触发
            Yii::import('CErrorEvent',true);
            $event=new CErrorEvent($this,$code,$message,$file,$line);
            $this->onError($event);
            // 如果错误事件未被处理
            if(!$event->handled)
            {
                // try an error handler
                if(($handler=$this->getErrorHandler())!==null)
                    $handler->handle($event);
                else
                    $this->displayError($code,$message,$file,$line);
            }
        }
        catch(Exception $e)
        {
            $this->displayException($e);
        }

        try
        {
            // 尝试触发onEndRequest事件
            $this->end(1);
        }
        catch(Exception $e)
        {
            // use the most primitive way to log error
            $msg = get_class($e).': '.$e->getMessage().' ('.$e->getFile().':'.$e->getLine().")\n";
            $msg .= $e->getTraceAsString()."\n";
            $msg .= "Previous error:\n";
            $msg .= $log."\n";
            $msg .= '$_SERVER='.var_export($_SERVER,true);
            error_log($msg);
            exit(1);
        }
    }
}

从上面代码可以看到，方法handleException的关键部分（handleError类似）为：

<?php
// 将异常封装成事件，并触发事件，从而触发监听该事件的处理过程
$event=new CExceptionEvent($this,$exception);
$this->onException($event);
// 如果事件并没有被处理（即没有监听该事件的处理过程）或者所有处理过程都没有将事件的handled属性置为true，则还得自己处理一下
if(!$event->handled)
{
    // try an error handler
    if(($handler=$this->getErrorHandler())!==null)
        $handler->handle($event);
    else
        $this->displayException($exception);
}

其中方法onException的实现如下：

<?php
public function onException($event)
{
    $this->raiseEvent('onException',$event);
}

raiseEvent方法实现如下：

<?php
public function raiseEvent($name,$event)
{
    // 根据事件名称，如onException，找到注册到该事件的处理过程，逐个触发调用。
    // 所有该事件注册的处理过程存放在$this->_e[$name]中
    $name=strtolower($name);
    if(isset($this->_e[$name]))
    {
        foreach($this->_e[$name] as $handler)
        {
            if(is_string($handler))
                call_user_func($handler,$event);
            elseif(is_callable($handler,true))
            {
                if(is_array($handler))
                {
                    // an array: 0 - object, 1 - method name
                    list($object,$method)=$handler;
                    if(is_string($object))  // static method call
                        call_user_func($handler,$event);
                    elseif(method_exists($object,$method))
                        $object->$method($event);
                    else
                        throw new CException(Yii::t('yii','Event "{class}.{event}" is attached with an invalid handler "{handler}".',
                            array('{class}'=>get_class($this), '{event}'=>$name, '{handler}'=>$handler[1])));
                }
                else // PHP 5.3: anonymous function
                    call_user_func($handler,$event);
            }
            else
                throw new CException(Yii::t('yii','Event "{class}.{event}" is attached with an invalid handler "{handler}".',
                    array('{class}'=>get_class($this), '{event}'=>$name, '{handler}'=>gettype($handler))));
            // stop further handling if param.handled is set true
            if(($event instanceof CEvent) && $event->handled)
                return;
        }
    }
    elseif(YII_DEBUG && !$this->hasEvent($name))
        throw new CException(Yii::t('yii','Event "{class}.{event}" is not defined.',
            array('{class}'=>get_class($this), '{event}'=>$name)));
}

那么是如何注册事件的处理过程的呢？

在类CComponent（见文件base/CComponent.php，CApplication类间接继承自该类）中定义了一对方法：attachEventHandler（将处理过程绑定到某事件）和detachEventHandler（将处理过程从事件解绑）。

方法attachEventHandler的实现如下：

<?php
public function attachEventHandler($name,$handler)
{
    $this->getEventHandlers($name)->add($handler);
}

其中getEventHandlers实现如下：

<?php
public function getEventHandlers($name)
{
    // 可以关注一下方法hasEvent
    // 检查是否存在$name对应的事件
    if($this->hasEvent($name))
    {
        $name=strtolower($name);
        if(!isset($this->_e[$name]))
            $this->_e[$name]=new CList;
        // 返回对应事件的处理过程列表
        return $this->_e[$name];
    }
    else
        throw new CException(Yii::t('yii','Event "{class}.{event}" is not defined.',
            array('{class}'=>get_class($this), '{event}'=>$name)));
}

回到“方法handleException的关键部分”，在事件的handled属性没有置为true的情况下，会调用方法getErrorHandler取到内置的一个处理过程，该方法实现如下：

<?php
public function getErrorHandler()
{
    // 获取名为errorHandler的组件，该组件默认会在CApplication类的registerCoreComponents方法中注册，
    // 见http://blog.xiayf.cn/2014/11/13/read-yii-code-3/一文的说明
    return $this->getComponent('errorHandler');
}

名为errorHandler的组件默认为类CErrorHandler（见文件base/CErrorHandler.php），当然也可以配置覆盖默认行为。

CErrorHandler类的handle方法实现如下：

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

    if($this->discardOutput)
    {
        $gzHandler=false;
        foreach(ob_list_handlers() as $h)
        {
            if(strpos($h,'gzhandler')!==false)
                $gzHandler=true;
        }
        // the following manual level counting is to deal with zlib.output_compression set to On
        // for an output buffer created by zlib.output_compression set to On ob_end_clean will fail
        for($level=ob_get_level();$level>0;--$level)
        {
            if(!@ob_end_clean())
                ob_clean();
        }
        // reset headers in case there was an ob_start("ob_gzhandler") before
        if($gzHandler && !headers_sent() && ob_list_handlers()===array())
        {
            if(function_exists('header_remove')) // php >= 5.3
            {
                header_remove('Vary');
                header_remove('Content-Encoding');
            }
            else
            {
                header('Vary:');
                header('Content-Encoding:');
            }
        }
    }

    // 异常和错误都可以调用handle方法
    if($event instanceof CExceptionEvent)
        $this->handleException($event->exception);
    else // CErrorEvent
        $this->handleError($event);
}

其中方法handleException和handleError实现分别如下：

<?php
protected function handleException($exception)
{
    $app=Yii::app();
    // 如果是Web应用
    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(
            // 如果抛出的异常是CHttpException类型，使用该异常自身的statusCode作为HTTP响应码，否则HTTP响应码为500
            // 所以在有意让Yii框架来处理抛出的异常时，需要明确指定异常的类型！
            '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']} ".$this->getHttpHeader($data['code'], get_class($exception)));

        // 判断异常类型
        // 对于CHttpException，也按照error来处理
        if($exception instanceof CHttpException || !YII_DEBUG)
            $this->render('error',$data);
        else
        {
            if($this->isAjaxRequest())
                $app->displayException($exception);
            else
                $this->render('exception',$data);
        }
    }
    // 如果是终端应用（console application），则直接展示异常
    else
        $app->displayException($exception);
}

<?php
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();
    // 如果是Web应用
    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';
        }
        // HTTP响应码为500
        $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 Internal Server Error");
        if($this->isAjaxRequest())
            $app->displayError($event->code,$event->message,$event->file,$event->line);
        elseif(YII_DEBUG)
            // 开了debug，则作为exception来处理
            $this->render('exception',$data);
        else
            $this->render('error',$data);
    }
    else
        $app->displayError($event->code,$event->message,$event->file,$event->line);
}

上面的代码最终显示异常/错误信息，是通过方法render、以及应用实例的displayError和displayException方法来完成。

render

<?php
protected function render($view,$data)
{
    // 注意这个地方，如果配置了errorAction，则可以指定目标controller的某个action来处理错误
    /*
     * 配置方式：
     * 'components' => array(
     *      'errorHandler' => array(
     *          'errorAction'=>'api/index/error',
     *     ),
     *     ...
     */
    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;

        // 看看下面getViewFile的实现
        include($this->getViewFile($view,$data['code']));
    }
}

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)
        {
             // 看看下面getViewFileInternal的实现
             $viewFile=$this->getViewFileInternal($viewPath,$view,$code,$i===2?'en_us':null);
             if(is_file($viewFile))
                 return $viewFile;
        }
    }
}

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;
}

上面代码的逻辑是 - 对于error类型的信息，Yii会依次在以下目录中寻找名为error{$code}.php文件来展示错误/异常信息：

WebRoot/themes/ThemeName/views/system
WebRoot/protected/views/system
yii/framework/views

如果没有找到，则以相同的次序在这些目录中查找error.php文件。

对于exception类型信息，则是查找exception.php文件。

所以如果应用开发过程需要定制4xx、5xx的错误页面，可以在WebRoot/protected/views/system或WebRoot/themes/ThemeName/views/system放置对应的错误模板页面。

displayError

<?php
public function displayError($code,$message,$file,$line)
{
    if(YII_DEBUG)
    {
        echo "<h1>PHP Error [$code]</h1>\n";
        echo "<p>$message ($file:$line)</p>\n";
        echo '<pre>';

        $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);
        foreach($trace as $i=>$t)
        {
            if(!isset($t['file']))
                $t['file']='unknown';
            if(!isset($t['line']))
                $t['line']=0;
            if(!isset($t['function']))
                $t['function']='unknown';
            echo "#$i {$t['file']}({$t['line']}): ";
            if(isset($t['object']) && is_object($t['object']))
                echo get_class($t['object']).'->';
            echo "{$t['function']}()\n";
        }

        echo '</pre>';
    }
    else
    {
        echo "<h1>PHP Error [$code]</h1>\n";
        echo "<p>$message</p>\n";
    }
}

displayException

<?php
public function displayException($exception)
{
    if(YII_DEBUG)
    {
        echo '<h1>'.get_class($exception)."</h1>\n";
        echo '<p>'.$exception->getMessage().' ('.$exception->getFile().':'.$exception->getLine().')</p>';
        echo '<pre>'.$exception->getTraceAsString().'</pre>';
    }
    else
    {
        echo '<h1>'.get_class($exception)."</h1>\n";
        echo '<p>'.$exception->getMessage().'</p>';
    }
}

总结

由上述分析可知，基于Yii框架开发应用时，有以下几点注意事项：

可以通过配置组件errorHandler的errorAction属性来定制异常/错误处理过程
可以通过在WebRoot/themes/ThemeName/views/system或WebRoot/protected/views/system放置模板（名为error{$code}.php）来定制错误/异常展示方式
在有意抛出异常由Yii框架捕获时，需明确异常的类型是否应为CHttpException，只有CHttpException实例初始化时指定的code才能成为HTTP响应码
可以对事件onError、onException绑定事件处理过程，进行额外的处理，比如记录错误/异常、触发告警等

数据与智能

Yii源码阅读笔记 - 错误/异常处理

概述

分析

总结

参考资料