README

使处理和调试 PHP 错误变得更加容易。

内容

• 特性
• 要求
• 使用示例
• 事件系统
  • 错误处理器事件
  • Web 错误屏幕事件
  • CLI 错误屏幕事件
  • 事件监听器示例

特性

• 普通/调试模式

• 将 PHP 错误（警告、通知等）转换为异常

• 尊重全局 error_reporting 设置

• 处理未捕获的异常和致命错误（包括解析错误和内存不足错误）

• CLI 错误屏幕将错误写入 stderr

• Web 错误屏幕渲染错误供网络浏览器查看

  • 普通模式显示通用错误消息：
  • 调试模式显示所有可用信息：
    • 文件路径和行号
    • 高亮代码预览
    • 堆栈跟踪
    • 参数列表
    • 输出缓冲区（也可以以 HTML 的形式显示）
    • 纯文本跟踪（用于复制粘贴）

• 可以用来

  • 实现日志记录
  • 条件性地抑制或强制错误
  • 更改或添加错误屏幕的内容

要求

• PHP 7.1+

使用示例

<?php

use Kuria\Error\ErrorHandler;

$debug = true; // true during development, false in production
error_reporting(E_ALL); // configure the error reporting

$errorHandler = new ErrorHandler();
$errorHandler->setDebug($debug);
$errorHandler->register();

// trigger an error to see the error handler in action
echo $invalidVariable;

事件系统

错误处理器事件

由 ErrorHandler 类可能发出的事件列在 ErrorHandlerEvents 中

ErrorHandlerEvents::ERROR

当发生 PHP 错误时发出。

参数

1. Kuria\Error\Exception\ErrorException $exception
   • 您可以使用 suppress() 或 force() 方法来抑制或强制异常，无论 PHP 的 error_reporting 设置如何
2. bool $debug

ErrorHandlerEvents::EXCEPTION

当处理未捕获的异常或致命错误时发出。

参数

1. Throwable $exception
2. bool $debug

警告

如果 $exception 是 Kuria\Error\Exception\OutOfMemoryException 的实例，请避免在此事件监听器中执行内存密集型任务。

ErrorHandlerEvents::FAILURE

当未捕获的异常或致命错误无法处理时发出。这可能发生在事件监听器或注册的错误屏幕抛出附加异常时。在此点抛出另一个异常或导致致命错误只会终止脚本。

参数

1. Throwable $exception
2. bool $debug

警告

如果 $exception 是 Kuria\Error\Exception\OutOfMemoryException 的实例，请避免在此事件监听器中执行内存密集型任务。

Web 错误屏幕事件

由 WebErrorScreen 类可能发出的事件列在 WebErrorScreenEvents 中

WebErrorScreenEvents::RENDER

在普通模式下渲染时发出。

接收包含以下键的数组

• &title: 用于 <title>
• &heading: 用于 <h1>
• &text: 默认段落的文本内容
• &extras: 主要部分之后的自定义 HTML
• exception: 异常
• output_buffer: string|null

WebErrorScreenEvents::RENDER_DEBUG

在调试模式下渲染时发出。

接收包含以下键的数组

• &title: 用于 <title>
• &extras: 主要部分之后的自定义 HTML
• exception: 异常
• output_buffer: string|null

WebErrorScreenEvents::CSS

当输出 CSS 样式时发出。

接收一个表示调试模式的布尔值。

WebErrorScreenEvents::JS

当输出 JavaScript 代码时发出。

接收一个表示调试模式的布尔值。

CLI 错误屏幕事件

由 CliErrorScreen 类可能发出的事件列在 CliErrorScreenEvents 中

CliErrorScreenEvents::RENDER

在普通模式下渲染时发出。

接收包含以下键的数组

• &title：输出第一行
• &output：错误信息
• exception: 异常
• output_buffer: string|null

CliErrorScreenEvents::RENDER_DEBUG

在调试模式下渲染时发出。

接收一个包含以下键的数组：ng 键

• &title：输出第一行
• &output：错误信息
• exception: 异常
• output_buffer: string|null

事件监听器示例

记录

将未捕获的异常记录到文件中

<?php

use Kuria\Debug\Error;
use Kuria\Error\ErrorHandlerEvents;

$errorHandler->on(ErrorHandlerEvents::EXCEPTION, function (\Throwable $exception, bool $debug) {
    $logFilePath = sprintf('./errors_%s.log', $debug ? 'dev' : 'prod');

    $entry = sprintf(
        "[%s] %s: %s in file %s on line %d\n",
        date('Y-m-d H:i:s'),
        Error::getExceptionName($exception),
        $exception->getMessage(),
        $exception->getFile(),
        $exception->getLine()
    );

    file_put_contents($logFilePath, $entry, FILE_APPEND | LOCK_EX);
});

禁用 "@" 操作符

此监听器会导致如 echo @$invalidVariable; 这样的语句无论 "shut-up" 操作符如何都抛出异常。

<?php

use Kuria\Error\Exception\ErrorException;
use Kuria\Error\ErrorHandlerEvents;

$errorHandler->on(ErrorHandlerEvents::ERROR, function (ErrorException $exception, bool $debug) {
    $exception->force();
});

修改错误屏幕

注意

示例针对 WebErrorScreen。

修改正常模式下的默认标签

<?php

use Kuria\Error\Screen\WebErrorScreen;
use Kuria\Error\Screen\WebErrorScreenEvents;

$errorScreen = $errorHandler->getErrorScreen();

if (!$errorHandler->isDebugEnabled() && $errorScreen instanceof WebErrorScreen) {
    $errorScreen->on(WebErrorScreenEvents::RENDER, function ($event) {
        $event['heading'] = 'It is all your fault!';
        $event['text'] = 'You have broken everything and now I hate you.';
    });
}

向调试屏幕添加自定义部分

<?php

use Kuria\Error\Screen\WebErrorScreen;
use Kuria\Error\Screen\WebErrorScreenEvents;

$errorScreen = $errorHandler->getErrorScreen();

if ($errorHandler->isDebugEnabled() && $errorScreen instanceof WebErrorScreen) {
    // add custom CSS
    $errorScreen->on(WebErrorScreenEvents::CSS, function () {
        echo '#custom-group {color: #f60000;}';
    });

    // add custom HTML
    $errorScreen->on(WebErrorScreenEvents::RENDER_DEBUG, function (array $view) {
        $view['extras'] .= <<<HTML
<div id="custom-group" class="group">
 <div class="section">
     Example of a custom section
 </div>
</div>
HTML;
       });
   }