README

此包提供了默认的 Slim 错误处理器和渲染器的替代方案。
它渲染带有堆栈跟踪和错误消息的样式化错误详细信息页面，或为生产环境提供通用错误页面。

可以创建自定义错误页面渲染器，通过实现 ErrorDetailsPageRendererInterface 或 GenericErrorPageRendererInterface 来更改错误页面的设计。

它还提供了一种 中间件，使项目“异常密集”，这意味着在开发和测试期间，它将像 Laravel 或 Symfony 等其他框架一样抛出带有堆栈跟踪的通知和警告异常。

预览

要求

• PHP 8.2+
• Composer
• Slim 4 应用程序

安装

使用 Composer 安装包

在你的项目根目录中打开终端，并运行以下命令

composer require samuelgfeller/slim-error-renderer

配置

以下配置值需要在设置中提供。根据开发、生产或测试 配置文件 适当修改。

文件： config/defaults.php

$settings['error'] = [
    // Must be set to false in production
    'display_error_details' => false,
    // Whether to log errors or not
    'log_errors' => true,
];

将错误处理中间件添加到 Slim 应用

容器实例化

如果你正在使用 依赖注入，将错误处理中间件添加到容器定义中（例如在 config/container.php 文件中）。ExceptionHandlingMiddleware 构造函数接受以下参数

1. 必需：实现 Psr\Http\Message\ResponseFactoryInterface 的响应工厂对象实例（有关默认实现，请参阅 此处）
2. 可选：实现 PSR 3 日志记录器 的实例以记录错误
3. 可选：布尔值，用于显示错误详情（文档：错误处理）
4. 可选：错误页面“报告错误”按钮上的联系邮箱
5. 可选：实现 SlimErrorRenderer\Interfaces\ProdErrorPageRendererInterface 的自定义通用错误页面渲染器
6. 可选：实现 SlimErrorRenderer\Interfaces\ErrorDetailsPageRendererInterface 的自定义错误详细信息页面渲染器

<?php

use SlimErrorRenderer\Middleware\ExceptionHandlingMiddleware;

return [
    // ...
    
    ExceptionHandlingMiddleware::class => function (ContainerInterface $container) {
        $settings = $container->get('settings');
        $app = $container->get(App::class);
        
        return new ExceptionHandlingMiddleware(
            $app->getResponseFactory(),
            $settings['error']['log_errors'] ? $container->get(LoggerInterface::class) : null,            
            $settings['error']['display_error_details'],
            $settings['public']['main_contact_email'] ?? null
        );
    },
    
    // ...
];

中间件栈

现在可以在 config/middleware.php 文件中将中间件添加到中间件栈中。
它应该是栈中的最后一个中间件，以捕获所有异常（Slim 中间件按添加的 逆序 执行）。
这替代了默认的 Slim 错误中间件。

<?php

use Slim\App;

return function (App $app) {
    // ...

    // Handle exceptions and display error page
    $app->add(ExceptionHandlingMiddleware::class);
}

“异常密集”中间件

当在 配置 中将 display_error_details 设置为 true 时，NonFatalErrorHandlingMiddleware 将警告和通知提升为异常。
这意味着通知和警告的错误详情将显示带有堆栈跟踪和错误消息。

容器实例化

NonFatalErrorHandlingMiddleware 也需要在容器中实例化。

构造函数接受三个参数

1. 必需：布尔值，用于显示错误详情
2. 必需：布尔值，用于记录警告/通知
3. 可选：PSR 3 日志记录器实例，用于记录警告/通知

<?php

use SlimErrorRenderer\Middleware\NonFatalErrorHandlingMiddleware;

return [
    // ...
    
    NonFatalErrorHandlingMiddleware::class => function (ContainerInterface $container) {
        $settings = $container->get('settings');
        
        return new NonFatalErrorHandlingMiddleware(
            $settings['error']['display_error_details'],
            $settings['error']['log_errors'] ? $container->get(LoggerInterface::class) : null,            
        );
    },
    
    // ...
];

添加到中间件堆栈

中间件应添加到堆栈中，位于 ExceptionHandlingMiddleware 之上。

文件：config/middleware.php

use Slim\App;

return function (App $app) {
    // ...

    // Promote warnings and notices to exceptions
    $app->add(NonFatalErrorHandlingMiddleware::class); // <- Add here
    // Handle exceptions and display error page
    $app->add(ExceptionHandlingMiddleware::class);
}

结论

请查看 slim-starter 以获取此包的默认实现，以及 slim-example-project 以获取具有布局的自定义 prod 错误页面。

为什么使用这个包？

这个小型库存在的原因不是使用默认的 Slim 错误处理器和一个 自定义错误渲染器，而是为了提供“异常密集型”功能和更美观的错误页面。
但是，这些可以通过自定义错误渲染器和位于项目中的中间件来实现。

默认的 Slim\Handlers\ErrorHandler 的问题在于，在测试时，错误处理器中的 $contentType 是 null，并且没有使用任何自定义错误渲染器，而是硬编码为使用 Slim\Error\Renderers\HtmlErrorRenderer。这有两个后果

1. 在集成测试中不会抛出错误，这意味着调试更困难。
2. 在预期抛出异常的测试中，会因 PHPUnit 11 警告 Test code or tested code did not remove its own error handlers 而失败。修复此消息的方法是调用 restore_error_handler()，但这无法完成，因为错误处理器在测试时不允许自定义错误渲染器。

因此，仍然需要自定义处理器，并且由于自定义渲染器和非致命错误的处理，将其放在单独的小型库中是有意义的。

许可证

本项目采用 MIT 许可证 - 请参阅 LICENSE 文件以获取详细信息。