错误和异常处理¶

自定义错误页面布局¶

默认情况下，错误模板使用 **templates/layout/error.php** 作为布局。您可以使用 layout 属性选择不同的布局

// inside templates/Error/error400.php
$this->layout = 'my_error';

以上将使用 **templates/layout/my_error.php** 作为错误页面的布局。

CakePHP 引发的许多异常将在调试模式下呈现特定的视图模板。在调试关闭的情况下，CakePHP 引发的所有异常将根据其状态代码使用 **error400.php** 或 **error500.php**。

更改 ErrorController 类¶

异常呈现器决定使用哪个控制器进行异常呈现。如果要更改用于呈现异常的控制器，请在您的异常呈现器中覆盖 _getController() 方法

// in src/Error/AppExceptionRenderer
namespace App\Error;

use App\Controller\SuperCustomErrorController;
use Cake\Controller\Controller;
use Cake\Error\Renderer\WebExceptionRenderer;

class AppExceptionRenderer extends WebExceptionRenderer
{
    protected function _getController(): Controller
    {
        return new SuperCustomErrorController();
    }
}

// in config/app.php
'Error' => [
    'exceptionRenderer' => 'App\Error\AppExceptionRenderer',
    // ...
],
// ...

记录异常¶

使用内置的异常处理，您可以通过在 **config/app.php** 中将 log 选项设置为 true 来记录 ErrorTrap 处理的所有异常。启用此功能会将每个异常记录到 Cake\Log\Log 和配置的记录器中。

HTTP 异常¶

CakePHP 中有几个内置异常，除了内部框架异常之外，还有几个用于 HTTP 方法的异常

exception Cake\Http\Exception\BadRequestException¶

用于执行 400 错误请求错误。

exception Cake\Http\Exception\UnauthorizedException¶

用于执行 401 未授权错误。

exception Cake\Http\Exception\ForbiddenException¶

用于执行 403 禁止错误。

exception Cake\Http\Exception\InvalidCsrfTokenException¶

用于执行由无效 CSRF 令牌引起的 403 错误。

exception Cake\Http\Exception\NotFoundException¶

用于执行 404 未找到错误。

exception Cake\Http\Exception\MethodNotAllowedException¶

用于执行 405 方法不允许错误。

exception Cake\Http\Exception\NotAcceptableException¶

用于执行 406 不可接受错误。

exception Cake\Http\Exception\ConflictException¶

用于执行 409 冲突错误。

exception Cake\Http\Exception\GoneException¶

用于执行 410 已消失错误。

有关 HTTP 4xx 错误状态代码的更多详细信息，请参阅 RFC 2616 第 10.4 节。

exception Cake\Http\Exception\InternalErrorException¶

用于执行 500 内部服务器错误。

exception Cake\Http\Exception\NotImplementedException¶

用于执行 501 未实现错误。

exception Cake\Http\Exception\ServiceUnavailableException¶

用于执行 503 服务不可用错误。

有关 HTTP 5xx 错误状态代码的更多详细信息，请参阅 RFC 2616 第 10.5 节。

您可以从控制器中抛出这些异常来指示失败状态或 HTTP 错误。 HTTP 异常的一个示例用法可能是为未找到的项目渲染 404 页面。

use Cake\Http\Exception\NotFoundException;

public function view($id = null)
{
    $article = $this->Articles->findById($id)->first();
    if (empty($article)) {
        throw new NotFoundException(__('Article not found'));
    }
    $this->set('article', $article);
    $this->viewBuilder()->setOption('serialize', ['article']);
}

通过使用异常来处理 HTTP 错误，您可以保持代码清洁，并为客户端应用程序和用户提供 RESTful 响应。

在控制器中使用 HTTP 异常¶

您可以从控制器操作中抛出任何与 HTTP 相关的异常来指示失败状态。 例如

use Cake\Network\Exception\NotFoundException;

public function view($id = null)
{
    $article = $this->Articles->findById($id)->first();
    if (empty($article)) {
        throw new NotFoundException(__('Article not found'));
    }
    $this->set('article', 'article');
    $this->viewBuilder()->setOption('serialize', ['article']);
}

上面的操作将导致配置的异常处理程序捕获并处理 NotFoundException。 默认情况下，这将创建一个错误页面并记录异常。

其他内置异常¶

此外，CakePHP 使用以下异常

exception Cake\View\Exception\MissingViewException¶

找不到选择的视图类。

exception Cake\View\Exception\MissingTemplateException¶

找不到选择的模板文件。

exception Cake\View\Exception\MissingLayoutException¶

找不到选择的布局。

exception Cake\View\Exception\MissingHelperException¶

找不到选择的辅助程序。

exception Cake\View\Exception\MissingElementException¶

找不到选择的元素文件。

exception Cake\View\Exception\MissingCellException¶

找不到选择的单元格类。

exception Cake\View\Exception\MissingCellViewException¶

找不到选择的单元格视图文件。

exception Cake\Controller\Exception\MissingComponentException¶

找不到配置的组件。

exception Cake\Controller\Exception\MissingActionException¶

找不到请求的控制器操作。

exception Cake\Controller\Exception\PrivateActionException¶

访问私有/受保护的/_ 前缀操作。

exception Cake\Console\Exception\ConsoleException¶

控制台库类遇到错误。

exception Cake\Database\Exception\MissingConnectionException¶

模型的连接丢失。

exception Cake\Database\Exception\MissingDriverException¶

找不到数据库驱动程序。

exception Cake\Database\Exception\MissingExtensionException¶

数据库驱动程序缺少 PHP 扩展。

exception Cake\ORM\Exception\MissingTableException¶

找不到模型的表格。

exception Cake\ORM\Exception\MissingEntityException¶

找不到模型的实体。

exception Cake\ORM\Exception\MissingBehaviorException¶

找不到模型的行为。

exception Cake\ORM\Exception\PersistenceFailedException¶

在使用 Cake\ORM\Table::saveOrFail() 或 Cake\ORM\Table::deleteOrFail() 时，实体无法保存/删除。

exception Cake\Datasource\Exception\RecordNotFoundException¶

找不到请求的记录。 这也会将 HTTP 响应头设置为 404。

exception Cake\Routing\Exception\MissingControllerException¶

找不到请求的控制器。

exception Cake\Routing\Exception\MissingRouteException¶

请求的 URL 无法反向路由或无法解析。

exception Cake\Core\Exception\Exception¶

CakePHP 中的基类异常。 CakePHP 抛出的所有框架层异常都将扩展此类。

这些异常类都扩展了 Exception。 通过扩展 Exception，您可以创建自己的“框架”错误。

Cake\Core\Exception\Exception::responseHeader($header = null, $value = null)¶

参见 Cake\Network\Request::header()

所有 Http 和 Cake 异常都扩展了 Exception 类，该类有一个方法可以将头添加到响应中。 例如，当抛出 405 MethodNotAllowedException 时，rfc2616 指出

"The response MUST include an Allow header containing a list of valid
methods for the requested resource."

自定义错误日志记录¶

错误处理程序使用 Cake\Error\ErrorLoggingInterface 的实例来创建日志消息并将它们记录到适当的位置。 您可以使用 Error.errorLogger 配置值替换错误记录器。 一个示例错误记录器

namespace App\Error;

use Cake\Error\ErrorLoggerInterface;
use Cake\Error\PhpError;
use Psr\Http\Message\ServerRequestInterface;
use Throwable;

/**
 * Log errors and unhandled exceptions to `Cake\Log\Log`
 */
class ErrorLogger implements ErrorLoggerInterface
{
    /**
     * @inheritDoc
     */
    public function logError(
        PhpError $error,
        ?ServerRequestInterface $request,
        bool $includeTrace = false
    ): void {
        // Log PHP Errors
    }

    /**
     * @inheritDoc
     */
    public function logException(
        ?ServerRequestInterface $request,
        bool $includeTrace = false
    ): void {
        // Log exceptions.
    }
}

自定义错误渲染¶

CakePHP 包含用于 Web 和控制台环境的错误渲染器。 但是，如果您想替换渲染错误的逻辑，您可以创建一个类

// src/Error/CustomErrorRenderer.php
namespace App\Error;

use Cake\Error\ErrorRendererInterface;
use Cake\Error\PhpError;

class CustomErrorRenderer implements ErrorRendererInterface
{
    public function write(string $out): void
    {
        // output the rendered error to the appropriate output stream
    }

    public function render(PhpError $error, bool $debug): string
    {
        // Convert the error into the output string.
    }
}

您的渲染器构造函数将传递一个包含所有 Error 配置的数组。 您可以通过 Error.errorRenderer 配置值将自定义错误渲染器连接到 CakePHP。 替换错误处理时，您需要同时考虑 Web 和命令行环境。