README

Yii 错误处理器

此包提供高级错误处理。功能包括

• PSR-15 中间件用于捕获未处理的错误。
• PSR-15 中间件用于将特定异常映射到自定义响应。
• 生产和调试模式。
• 调试模式显示详细信息、堆栈跟踪，具有深色和浅色主题，并提供了方便的按钮，无需输入即可搜索错误。
• 考虑 PHP 设置。
• 处理内存不足错误、致命错误、警告、通知和异常。
• 可以使用任何 PSR-3 兼容的记录器进行错误记录。
• 根据请求的 MIME 类型检测响应格式。
• 直接支持使用 HTML、纯文本、JSON、XML 和头信息进行响应。
• 具有实现您自己的错误渲染以支持其他类型的可能性。
• 友好的异常 支持。

要求

• PHP 8.0 或更高版本。
• DOM PHP 扩展。
• JSON PHP 扩展。
• mbstring PHP 扩展。

安装

可以使用 Composer 安装此包

composer require yiisoft/error-handler

通用用法

创建错误处理器

use Yiisoft\ErrorHandler\ErrorHandler;
use Yiisoft\ErrorHandler\Renderer\HtmlRenderer;

/**
 * @var \Psr\Log\LoggerInterface $logger
 */

$errorHandler = new ErrorHandler($logger, new HtmlRenderer());

错误处理器使用任何 PSR-3 兼容的记录器记录有关错误的信息。如果出于某种原因您不想记录错误信息，请指定一个 \Psr\Log\NullLogger 实例。

默认情况下，错误处理器设置为生产模式，不显示详细信息。您可以通过以下方式启用和禁用调试模式

// Enable debug mode:
$errorHandler->debug();

// Disable debug mode:
$errorHandler->debug(false);

// Or define the environment dynamically:
$errorHandler->debug($_ENV['debug'] ?? false);

错误处理器处理内存不足错误。为了实现这一点，预先分配内存，以便如果发生内存不足的问题，错误处理器可以使用保留内存来处理错误。您可以使用 memoryReserveSize() 方法指定自己的保留大小。如果将此值设置为 0，则不保留内存。

// Allocate 512KB. Defaults to 256KB.
$errorHandler->memoryReserveSize(524_288);

使用 register() 方法注册 PHP 错误和异常处理器。要注销这些并恢复 PHP 错误和异常处理器，请使用 unregister() 方法。

$errorHandler->register();
// Errors are being handled.
$errorHandler->unregister();
// Errors are not handled.

渲染错误数据

以下是一些内置的渲染器

• Yiisoft\ErrorHandler\Renderer\HeaderRenderer - 将错误渲染为 HTTP 头部。用于 HEAD 请求。
• Yiisoft\ErrorHandler\Renderer\HtmlRenderer - 将错误渲染为 HTML。
• Yiisoft\ErrorHandler\Renderer\JsonRenderer - 将错误渲染为 JSON。
• Yiisoft\ErrorHandler\Renderer\PlainTextRenderer - 将错误渲染为纯文本。
• Yiisoft\ErrorHandler\Renderer\XmlRenderer - 将错误渲染为 XML。

如果现有的渲染器不足以满足需求，您可以创建自己的。为此，您必须实现 Yiisoft\ErrorHandler\ThrowableRendererInterface 并在创建错误处理器实例时指定它。

use Yiisoft\ErrorHandler\ErrorHandler;

/**
 * @var \Psr\Log\LoggerInterface $logger
 * @var \Yiisoft\ErrorHandler\ThrowableRendererInterface $renderer
 */

$errorHandler = new ErrorHandler($logger, $renderer);

有关创建自己的渲染器和渲染错误数据的示例，请参阅此处。

使用中间件捕获未处理的错误

Yiisoft\ErrorHandler\Middleware\ErrorCatcher 是一个 PSR-15 中间件，用于捕获在中间件堆栈执行过程中出现的异常，并将它们传递给处理器。

use Yiisoft\ErrorHandler\Middleware\ErrorCatcher;

/**
 * @var \Psr\Container\ContainerInterface $container
 * @var \Psr\Http\Message\ResponseFactoryInterface $responseFactory
 * @var \Psr\Http\Message\ServerRequestInterface $request
 * @var \Psr\Http\Server\RequestHandlerInterface $handler
 * @var \Yiisoft\ErrorHandler\ErrorHandler $errorHandler
 * @var \Yiisoft\ErrorHandler\ThrowableRendererInterface $renderer
 */

$errorCatcher = new ErrorCatcher($responseFactory, $errorHandler, $container);

// In any case, it will return an instance of the `Psr\Http\Message\ResponseInterface`.
// Either the expected response, or a response with error information.
$response = $errorCatcher->process($request, $handler);

错误捕获器根据接受 HTTP 头选择如何渲染异常。如果是 text/html 或任何未知的内容类型，它将使用错误或异常 HTML 模板来显示错误。对于其他 MIME 类型，错误处理器将选择错误捕获器内注册的不同渲染器。默认支持 JSON、XML 和纯文本。您可以通过以下方式更改此行为

// Returns a new instance without renderers by the specified content types.
$errorCatcher = $errorCatcher->withoutRenderers('application/xml', 'text/xml');

// Returns a new instance with the specified content type and renderer class.
$errorCatcher = $errorCatcher->withRenderer('my/format', new MyRenderer());

// Returns a new instance with the specified force content type to respond with regardless of request.
$errorCatcher = $errorCatcher->forceContentType('application/json');

使用中间件将某些异常映射到自定义响应

Yiisoft\ErrorHandler\Middleware\ExceptionResponder 是一个 PSR-15 中间件，它将某些异常映射到自定义响应。

use Yiisoft\ErrorHandler\Middleware\ExceptionResponder;

/**
 * @var \Psr\Http\Message\ResponseFactoryInterface $responseFactory
 * @var \Psr\Http\Message\ServerRequestInterface $request
 * @var \Psr\Http\Server\RequestHandlerInterface $handler
 * @var \Yiisoft\Injector\Injector $injector
 */
 
$exceptionMap = [
    // Status code with which the response will be created by the factory.
    MyNotFoundException::class => 404,
    // PHP callable that must return a `Psr\Http\Message\ResponseInterface`.
    MyHttpException::class => static fn (MyHttpException $exception) => new MyResponse($exception),
    // ...
];

$exceptionResponder = new ExceptionResponder($exceptionMap, $responseFactory, $injector);

// Returns the expected response, or the response associated with the thrown exception,
// or throws an exception if it does not present in the exception map.
$response = $exceptionResponder->process($request, $handler);

在应用程序中间件堆栈中，必须将 Yiisoft\ErrorHandler\Middleware\ExceptionResponder 放在 Yiisoft\ErrorHandler\Middleware\ErrorCatcher 之前。

事件

• 当 ErrorCatcher 捕获错误时，它将派发 \Yiisoft\ErrorHandler\Event\ApplicationError 事件。

友好的异常

HtmlRenderer 支持 友好的异常。

在解决方案的 markdown 代码块中支持语言语法高亮

例如

<html>
<body>
    <p>This text is normal.</p>
    <p><b>This text is bold.</b></p>
</body>
</html>

文档

• Yii 错误处理指南
• 内部

如果您需要帮助或有问题，请访问 Yii 论坛，那里是个好去处。您还可以查看其他 Yii 社区资源。

许可

Yii 错误处理器是免费软件。它根据 BSD 许可证条款发布。有关更多信息，请参阅 LICENSE。

由 Yii 软件 维护。

致谢

Yii 错误处理器使用了 Ivan Sagalaev 和其他贡献者提供的 Highlight.js 代码。

支持项目

关注更新