异常

异常

异常在应用程序中可以用作不同的用途。CakePHP 在内部使用异常来表示逻辑错误或用法错误。所有 CakePHP 抛出的异常都扩展了 CakeException，类/任务相关的异常扩展了这个基类。

CakePHP 也提供了一些异常类，可用于 HTTP 错误。欲知更多信息，可参看CakePHP 的内置异常一节。

异常的配置

有一些键可用于配置异常:

Configure::write('Exception', array(
    'handler' => 'ErrorHandler::handleException',
    'renderer' => 'ExceptionRenderer',
    'log' => true
));

handler - callback - 处理异常的回调函数。可以设置它为任何回调类型，包括匿名函数。
renderer - string - 负责渲染未捕获异常的类。如果选择自定义类，应当把这个类的文件放入 app/Lib/Error 目录中。这个类需要实现 render() 方法。
log - boolean - 为 true 时，异常 + 它们的堆栈跟踪会被记录到 CakeLog 中。
consoleHandler - callback - 在控制台的环境中，用来处理异常的回调函数。如果没有定义，就会使用 CakePHP 默认的处理器。
异常的渲染在默认情况下会显示一个 HTML 页面，你可以通过改变设置来自定义处理器或者渲染器。改变处理器，让你可以完全控制异常的处理过程，而改变渲染器让你容易地改变输出类型和内容，以及加进应用程序相关的异常处理。

2.2 新版功能: 在 2.2 版本中加入了 Exception.consoleHandler 选项。

Exception 类

CakePHP 中有一些异常类。每个异常取代了过去的一个 cakeError() 错误消息。异常提供了更多的灵活性，因为它们可以扩展，也可以包含一些逻辑。内置的异常处理会捕获任何未捕获的异常，渲染一个有所帮助的页面。没有特意使用 400 范围的代码的异常，会被当作内部服务器错误(Internal Server Error)。

CakePHP 的内置异常

在 CakePHP 中，除了框架内部的异常，有一些内置的异常，有几个专门针对 HTTP 方法(method)的异常

exception BadRequestException
用于处理 400 错误的请求(Bad Request)错误。
exception UnauthorizedException
用于处理 401 未授权(Unauthorized)错误。
exception ForbiddenException
用于处理 403 禁止访问(Forbidden)错误。
exception NotFoundException
用于处理 404 未找到(Not found)错误。
exception MethodNotAllowedException
用于处理 405 方法不被允许(Method Not Allowed)错误。
exception InternalErrorException
用于处理 500 内部服务器错误(Internal Server Error)。
exception NotImplementedException
用于处理 501 未实现(Not Implemented)错误。

你可以从控制器抛出这些异常，表示错误状态或 HTTP 错误。使用 HTTP 异常的一个例子可以是，对未找到的数据渲染 404 页面:

public function view($id) {
    $post = $this->Post->findById($id);
    if (!$post) {
        throw new NotFoundException('Could not find that post');
    }
    $this->set('post', $post);
}

通过对 HTTP 错误使用异常，你可以在保持代码整洁的同时，对客户端应用程序和用户提供RESTful 响应。

另外，还有以下框架层的异常，会从 CakePHP 的一些核心组件抛出：

exception MissingViewException
无法找到选中的视图(view)文件。
exception MissingLayoutException
无法找到选中的布局(layout)。
exception MissingHelperException
无法找到助件(helper)。
exception MissingBehaviorException
无法找到配置的行为(behavior)。
exception MissingComponentException
无法找到配置的组件(component)。
exception MissingTaskException
无法找到配置的任务。
exception MissingShellException
无法找到外壳类(shelll class)。
exception MissingShellMethodException
选中的外壳类(shelll class)没有该命名的方法。
exception MissingDatabaseException
无法找到配置的数据库。
exception MissingConnectionException
模型的连接缺失。
exception MissingTableException
模型的表无法在 CakePHP 的缓存或数据源中找到。在向数据源添加一个新表之后，模型缓存(默认在 tmp/cache/models 目录中)必须清除。
exception MissingActionException
无法找到请求的控制器动作。
exception MissingControllerException
无法找到请求的控制器。
exception PrivateActionException
访问私有动作。或者是试图访问 private/protected/前缀为 _ 的动作，或者是试图不正确地访问前缀路由。
exception CakeException
CakePHP 的异常基类。CakePHP 抛出的所有框架层基类都要扩展这个类。

这些异常类都扩展 CakeException。通过扩展 CakeException，你可以创建自己的'框架'错误。CakePHP 会抛出的所有标准异常都扩展了 CakeException。

2.3 新版功能: 添加了 CakeBaseException。

exception CakeBaseException
CakePHP 的异常基类。所有上面的 CakeExceptions 和 HttpException 扩展这个类。
CakeBaseException::responseHeader($header = null, $value = null)
参看 CakeResponse::header()。

所有 Http 和 CakePHP 异常扩展 CakeBaseException 类，该类有一个方法添加头部信息到响应。例如在抛出 405 MethodNotAllowedException 时，rfc2616 指出："响应必须包括一个 Allow 头部信息，包含一个对请求的资源的合法方法的列表。"

在控制器中使用 HTTP 异常

你可以从控制器动作中抛出任何 HTTP 相关的异常来表示错误状态。例如:

public function view($id) {
    $post = $this->Post->findById($id);
    if (!$post) {
        throw new NotFoundException();
    }
    $this->set(compact('post'));
}

上述代码会使配置的 Exception.handler 捕获和处理 NotFoundException。默认情况下，这会导致一个错误页面，并记录该异常。

异常的渲染器

class ExceptionRenderer(Exception $exception)
在 CakeErrorController 的协助下，ExceptionRenderer 类负责为所有应用程序抛出的异常渲染错误页面。

错误页面的视图在 app/View/Errors/ 目录中。对所有 4xx 和 5xx 错误，分别使用视图文件 error400.ctp 和 error500.ctp。你可以根据需要定制这些视图。默认情况下，错误页面也使用布局 app/Layouts/default.ctp。如果想要对错误页面使用另一个布局，例如 app/Layouts/my_error.ctp，那么只需编辑错误视图，添加语句$this->layout = 'my_error'; 到 error400.ctp 和 error500.ctp。

每个框架层异常都有自己位于核心模板中的视图文件，但你真的不必定制它们，因为它们只在开发过程中使用。在关闭调试后，所有框架层异常都会转变为InternalErrorException。

创建你自己的应用程序的异常

你可以使用任何内置的SPL exceptions 、 Exception本身或 CakeException 来创建你自己的应用程序的异常。扩展 Exception 类或者 SPL 异常的应用程序异常在生产模式下会被当作 500 错误对待。CakeException 比较特别，所有 CakeException 对象会根据它们使用的编码被强制转换为 500 或 404 错误。在开发模式下，CakeException对象只需新增一个匹配类名的新模板就能提供有用的信息。如果应用程序包含如下异常:

class MissingWidgetException extends CakeException {};

你可以创建 app/View/Errors/missing_widget.ctp，就能提供良好的开发错误提示。在生产模式下，上述错误会被当作 500 错误。CakeException 的构造函数被扩展了，让你可以传入数据数组。该数组会被嵌入 messageTemplate 模板、以及在开发模式下表示错误的视图中。这让你可以通过为错误提供更多的上下文，来创建富含数据的异常。你也可以提供消息模板，让原生的 __toString() 方法可以正常工作:

class MissingWidgetException extends CakeException {
    protected $_messageTemplate = 'Seems that %s is missing.';
}
 
throw new MissingWidgetException(array('widget' => 'Pointy'));

当被内置的异常处理器捕获时，在错误视图模板中会得到一个 $widget 变量。而且，如果把异常转换(cast)为字符串，或者调用它的 getMessage() 方法，就会得到Seems that Pointy is missing.。这让你可以轻松快速地创建你自己富含(信息)的开发错误，就像 CakePHP 内部使用的一样。

创建自定义状态编码

在创建异常时改变编码，就能创建自定义的 HTTP 状态编码:

throw new MissingWidgetHelperException('Its not here', 501);

就会创建一个 501 响应编码，你可以使用任何 HTTP 状态编码。在开发中，如果你的异常没有一个特定的模板，而你使用了大于等于 500 的编码，你就会看到error500 模板。对于任何其它错误编码，就会得到 error400 模板。如果你为自定义异常定义了错误模板，在开发模式下就会使用该模板。如果你甚至在生产环境中也要使用自己的异常处理逻辑，请看下一节。

扩展和实现你自己的异常处理器

你有几种方式实现应用程序相关的异常处理。每种方式给你提供对异常处理过程的不同控制。

设置 Configure::write('Exception.handler', 'YourClass::yourMethod');
创建 AppController::appError();
设置 Configure::write('Exception.renderer', 'YourClass');
在下面几节中，我们会详细描述每种方式不同的方法和好处。

用 Exception.handler 创建你自己的异常处理器

创建你自己的异常处理器，给你提供了对异常处理过程的完全控制。你选择的类应当在app/Config/bootstrap.php 文件中加载，这样它才能够用于处理任何异常。你可以把处理器定义为任何回调类型。设置了 Exception.handler，CakePHP 就会忽略所有其它的异常设置。下面就是一个自定义异常处理设置的例子:

// in app/Config/core.php
Configure::write('Exception.handler', 'AppExceptionHandler::handle');
 
// in app/Config/bootstrap.php
App::uses('AppExceptionHandler', 'Lib');
 
// in app/Lib/AppExceptionHandler.php
class AppExceptionHandler {
    public static function handle($error) {
        echo 'Oh noes! ' . $error->getMessage();
        // ...
    }
    // ...
}

你可以在 handleException 方法中运行任何你想要运行的代码。上面的代码会输出'Oh noes! ' 加上异常消息。你可以定义处理器为任何类型的回调，如果使用 PHP 5.3甚至可以是匿名函数:

Configure::write('Exception.handler', function ($error) {
    echo 'Ruh roh ' . $error->getMessage();
});

通过创建自定义异常处理器，你可以为应用程序的异常提供自定义错误处理。在提供作为异常处理器的方法中，你可以这么做:

// in app/Lib/AppErrorHandler.php
class AppErrorHandler {
    public static function handleException($error) {
        if ($error instanceof MissingWidgetException) {
            return self::handleMissingWidget($error);
        }
        // 做其它事情。
    }
}

使用 AppController::appError()

实现该方法是实现自定义异常处理器的另一种方法。这主要是为向后兼容而提供的，新的应用程序不建议使用。会调用这个控制器方法，而不会调用默认的异常渲染过程。这只接受抛出的异常作为其唯一的参数。应当在这个方法中实现错误处理:

class AppController extends Controller {
    public function appError($error) {
        // 这里是自定义逻辑。
    }
}

在 Exception.renderer 使用自定义渲染器来处理应用程序异常

如果你不想控制异常处理，但要改变如何渲染异常，你可以用 Configure::write( 'Exception.renderer', 'AppExceptionRenderer'); 选择一个类来渲染异常页面。默认情况下会使用 :php:classExceptionRenderer。你的自定义异常渲染类应当放在app/Lib/Error 目录中，或者在一个启动加载的 Lib 路径内的 Error 目录内。在自定义异常渲染类中，你可以为应用程序相关的错误提供特殊的处理:

// in app/Lib/Error/AppExceptionRenderer.php
App::uses('ExceptionRenderer', 'Error');
 
class AppExceptionRenderer extends ExceptionRenderer {
    public function missingWidget($error) {
        echo 'Oops that widget is missing!';
    }
}

上述代码会处理任何 MissingWidgetException 类型的异常，让你可以为这些应用程序异常提供自定义的显示/处理逻辑。异常处理方法接受被处理的异常为它们的参数。

注解

你的自定义渲染器在构造函数中期待一个异常，并要实现 render 方法。不这么做会引起额外的错误。

注解

如果你使用自定义 Exception.handler，该设置就会无效，除非在你的实现中引用它。

创建自定义控制器来处理异常

在你的 ExceptionRenderer 子类中，你可以用 _getController 方法来返回自定义控制器来处理错误。默认情况下，CakePHP 使用 CakeErrorController，这会省略一些正常的回调，以帮助确保总能显示错误。不过，你可能在应用程序中需要一个更加定制化的错误处理控制器。在你的 AppExceptionRenderer 类中实现 _getController 方法，你就能使用任何你想用的控制器:

class AppExceptionRenderer extends ExceptionRenderer {
    protected function _getController($exception) {
        App::uses('SuperCustomError', 'Controller');
        return new SuperCustomErrorController();
    }
}

或者，你可以在 app/Controller 目录中引入核心的 CakeErrorController，来重载它。如果你使用自定义控制器来进行错误处理，确保在构造函数或 render 方法中进行了所有需要的设置，因为这些是内置的 ErrorHandler 类唯一直接调用的方法。

在日志中记录异常

用内置的异常处理，你只要在 core.php 文件中设置 Exception.log 为 true，就可以在日志中记录所有由 ErrorHandler 处理的异常。启用之后，就会把每个异常记录到CakeLog 和配置的日志中。

注解

如果你使用自定义的 Exception.handler，这个设置就不起作用，除非在你的实现中引用它。