#Ignition：PHP 应用程序的精美错误页面

Ignition 是 PHP 应用程序的精美且可自定义的错误页面

这是一个关于如何注册 Ignition 的最小示例。

use Spatie\Ignition\Ignition;
 
include 'vendor/autoload.php';
 
Ignition::make()->register();

现在，让我们在 Web 请求期间抛出异常。

throw new Exception('Bye world');

这是您将在浏览器中看到的内容。

还有一种精美的深色模式。

#您是视觉学习者吗？

在 YouTube 上的此视频 中，您将看到所有功能的演示。

您想知道有关我们做出的设计决策的更多信息，请阅读 这篇博文。

#支持我们

我们在创建 一流的开源软件包 上投入了大量资源。您可以通过 购买我们的一款付费产品 来支持我们。

我们非常感谢您从您的家乡寄给我们明信片，并提及您正在使用我们的哪个软件包。您可以在 我们的联系页面 上找到我们的地址。我们会在 我们的虚拟明信片墙 上发布收到的所有明信片。

#安装

对于 Laravel 应用程序，请访问 laravel-ignition。

对于 Symfony 应用程序，请访问 symfony-ignition-bundle。

对于所有其他 PHP 项目，请通过 composer 安装软件包

composer require spatie/ignition

#用法

为了在您的项目中发生错误时显示 Ignition 错误页面，您必须添加此代码。通常，这将在您的应用程序的引导部分完成。

\Spatie\Ignition\Ignition::make()->register();

#设置应用程序路径

在设置应用程序路径时，Ignition 将从所有路径中修剪给定的值。这将使错误页面看起来更简洁。

\Spatie\Ignition\Ignition::make()
    ->applicationPath($basePathOfYourApplication)
    ->register();

#使用深色模式

默认情况下，Ignition 使用一个漂亮的白色主题。如果这对您的眼睛来说太亮，您可以使用深色模式。

\Spatie\Ignition\Ignition::make()
    ->useDarkMode()
    ->register();

#避免在生产环境中呈现 Ignition

您不希望在生产环境中呈现 Ignition 错误页面，因为它可能会显示敏感信息。

要避免呈现 Ignition，您可以调用 shouldDisplayException 并向其传递一个假值。

\Spatie\Ignition\Ignition::make()
    ->shouldDisplayException($inLocalEnvironment)
    ->register();

#显示解决方案

除了显示异常之外，Ignition 还可以显示解决方案。

开箱即用，Ignition 将显示针对常见错误的解决方案，例如错误的方法调用或使用未定义的属性。

#将解决方案直接添加到异常

要将解决方案文本添加到您的异常，请让异常实现 Spatie\Ignition\Contracts\ProvidesSolution 接口。

此接口要求您实现一个方法，该方法将返回用户在抛出异常时将看到的 Solution。

use Spatie\Ignition\Contracts\Solution;
use Spatie\Ignition\Contracts\ProvidesSolution;
 
class CustomException extends Exception implements ProvidesSolution
{
    public function getSolution(): Solution
    {
        return new CustomSolution();
    }
}

use Spatie\Ignition\Contracts\Solution;
 
class CustomSolution implements Solution
{
    public function getSolutionTitle(): string
    {
        return 'The solution title goes here';
    }
 
    public function getSolutionDescription(): string
    {
        return 'This is a longer description of the solution that you want to show.';
    }
 
    public function getDocumentationLinks(): array
    {
        return [
            'Your documentation' => 'https://your-project.com/relevant-docs-page',
        ];
    }
}

如果您要抛出异常，这就是异常的显示方式。

#使用解决方案提供程序

与其将解决方案直接添加到异常，您还可以创建解决方案提供程序。虽然返回解决方案的异常会直接向 Ignition 提供解决方案，但解决方案提供程序允许您弄清楚是否可以解决异常。

例如，您可以创建一个自定义的“Stack Overflow 解决方案提供程序”，它将查找是否可以找到针对给定可抛出对象的解决方案。

解决方案提供程序可以由第三方软件包或您自己的应用程序添加。

解决方案提供程序是任何实现 \Spatie\Ignition\Contracts\HasSolutionsForThrowable 接口的类。

这就是接口的样子

interface HasSolutionsForThrowable
{
    public function canSolve(Throwable $throwable): bool;
 
    /** @return \Spatie\Ignition\Contracts\Solution[] */
    public function getSolutions(Throwable $throwable): array;
}

当您的应用程序中发生错误时，该类将在 canSolve 方法中接收 Throwable。在该方法中，您可以决定您的解决方案提供程序是否适用于传递的 Throwable。如果您返回 true，getSolutions 将被调用。

要将解决方案提供程序注册到 Ignition，您必须调用 addSolutionProviders 方法。

\Spatie\Ignition\Ignition::make()
    ->addSolutionProviders([
        YourSolutionProvider::class,
        AnotherSolutionProvider::class,
    ])
    ->register();

#AI 驱动的解决方案

Ignition 可以将您的异常发送到 Open AI，它将尝试自动建议解决方案。在许多情况下，建议的解决方案非常有用，但请记住，解决方案可能不完全适合您的上下文。

要生成 AI 驱动的解决方案，您必须先安装此可选依赖项。

composer require openai-php/client

要开始将您的错误发送到 OpenAI，您必须实例化 OpenAiSolutionProvider。构造函数需要传递一个 OpenAI API 密钥，您应该在 OpenAI 上生成此密钥。

use \Spatie\Ignition\Solutions\OpenAi\OpenAiSolutionProvider;
 
$aiSolutionProvider = new OpenAiSolutionProvider($openAiKey);

要使用解决方案提供程序，您应该在注册 Ignition 时将其传递给 addSolutionProviders。

\Spatie\Ignition\Ignition::make()
    ->addSolutionProviders([
        $aiSolutionProvider,
        // other solution providers...
    ])
    ->register();

默认情况下，解决方案提供程序会将这些信息发送到 Open AI

• 错误消息
• 错误类
• 堆栈帧
• 与错误相关的其他少量上下文信息

它不会发送请求有效负载或任何环境变量，以避免将敏感数据发送到 OpenAI。

#缓存对 AI 的请求

默认情况下，所有错误都将发送到 OpenAI。可选地，您可以添加缓存，以便类似的错误只会发送到 OpenAI 一次。要缓存错误，您可以在 $aiSolutionProvider 上调用 useCache。您应该传递一个 简单缓存实现。这是 useCache 方法的签名。

public function useCache(CacheInterface $cache, int $cacheTtlInSeconds = 60 * 60)

#提示应用程序类型

为了提高建议解决方案的质量，您可以将应用程序类型（Symfony、Drupal、WordPress 等）发送到 AI。

要发送应用程序类型，请在解决方案提供程序上调用 applicationType。

$aiSolutionProvider->applicationType('WordPress 6.2')

#将异常发送到 Flare

Ignition 具有将异常发送到 Flare（一个异常监控服务）的功能。Flare 可以在您的生产环境中发生新的异常时通知您。

要将异常发送到 Flare，只需调用 sendToFlareMethod 并向其传递在 Flare 上创建项目时获得的 API 密钥。

您可能希望将此与调用 runningInProductionEnvironment 相结合。该方法在传递一个真值时，不会显示 Ignition 错误页面，而只会将异常发送到 Flare。

\Spatie\Ignition\Ignition::make()
    ->runningInProductionEnvironment($boolean)
    ->sendToFlare($yourApiKey)
    ->register();

当您将假值传递给 runningInProductionEnvironment 时，将显示 Ignition 错误页面，但不会将异常发送到 Flare。

#发送自定义上下文到 Flare

当您将错误发送到 Flare 时，您可以添加自定义信息，这些信息将与应用程序中发生的每个异常一起发送。如果您想提供有助于调试可能出现的异常的键值相关信息，这将非常有用。

use Spatie\FlareClient\Flare;
 
\Spatie\Ignition\Ignition::make()
    ->runningInProductionEnvironment($boolean)
    ->sendToFlare($yourApiKey)
    ->configureFlare(function(Flare  $flare) {
        $flare->context('Tenant', 'My-Tenant-Identifier');
    })
    ->register();

有时您可能希望按您提供的键对上下文项进行分组，以便在查看自定义上下文项时更容易进行视觉区分。

Flare 客户端允许您像这样提供您自己的自定义上下文组

use Spatie\FlareClient\Flare;
 
\Spatie\Ignition\Ignition::make()
    ->runningInProductionEnvironment($boolean)
    ->sendToFlare($yourApiKey)
    ->configureFlare(function(Flare  $flare) {
        $flare->group('Custom information', [
            'key' => 'value',
            'another key' => 'another value',
        ]);
    })
    ->register();

#匿名化请求到 Flare

默认情况下，Ignition 会收集有关应用程序用户 IP 地址的信息。如果您不想将此信息发送到 Flare，请调用 anonymizeIp()。

use Spatie\FlareClient\Flare;
 
\Spatie\Ignition\Ignition::make()
    ->runningInProductionEnvironment($boolean)
    ->sendToFlare($yourApiKey)
    ->configureFlare(function(Flare  $flare) {
        $flare->anonymizeIp();
    })
    ->register();

#审查请求正文字段

当 Web 请求中发生异常时，Flare 客户端将传递正文中存在的任何请求字段。

在某些情况下，例如登录页面，这些请求字段可能包含您不想发送到 Flare 的密码。

要审查某些字段的值，可以使用 censorRequestBodyFields。您应该将要审查的字段名称传递给它。

use Spatie\FlareClient\Flare;
 
\Spatie\Ignition\Ignition::make()
    ->runningInProductionEnvironment($boolean)
    ->sendToFlare($yourApiKey)
    ->configureFlare(function(Flare  $flare) {
        $flare->censorRequestBodyFields(['password']);
    })
    ->register();

这将用值 <CENSORED> 替换任何名为“password”的发送字段的值。

#使用中间件修改发送到 Flare 的数据

在 Flare 接收到从本地异常收集的数据之前，我们为您提供了调用自定义中间件方法的能力。这些方法检索应发送到 Flare 的报告，并允许您向该报告添加自定义信息。

有效的中间件是实现 FlareMiddleware 的任何类。

use Spatie\FlareClient\Report;
 
use Spatie\FlareClient\FlareMiddleware\FlareMiddleware;
 
class MyMiddleware implements FlareMiddleware
{
    public function handle(Report $report, Closure $next)
    {
        $report->message("{$report->getMessage()}, now modified");
 
        return $next($report);
    }
}

use Spatie\FlareClient\Flare;
 
\Spatie\Ignition\Ignition::make()
    ->runningInProductionEnvironment($boolean)
    ->sendToFlare($yourApiKey)
    ->configureFlare(function(Flare  $flare) {
        $flare->registerMiddleware([
            MyMiddleware::class,
        ])
    })
    ->register();

#变更日志

有关最近更改的更多信息，请参阅 CHANGELOG。

#贡献

有关详细信息，请参阅 CONTRIBUTING。

#开发设置

以下是在您想开发 Ignition UI 时需要执行的步骤。

• 将 spatie/ignition、spatie/ignition-ui、spatie/laravel-ignition、spatie/flare-client-php 和 spatie/ignition-test 克隆（或移动）到同一个目录（例如 ~/code/flare）
• 在 ~/code/flare 目录中创建一个新的 package.json 文件

{
    "private": true,
    "workspaces": [
        "ignition-ui",
        "ignition"
    ]
}

• 在 ~/code/flare 目录中运行 yarn install
• 在 ~/code/flare/ignition-test 目录中
  • 运行 composer update
  • 运行 cp .env.example .env
  • 运行 php artisan key:generate
• 在 ignition 和 ignition-ui 项目中运行 yarn dev
• http://ignition-test.test/ 现在应该可以工作（= 显示新的 UI）。如果您使用 valet，您可能需要在 ~/code/flare 目录中运行 valet park。
  • http://ignition-test.test/ 具有所有内容
  • http://ignition-test.test/sql-error 包含解决方案和 SQL 异常

#安全漏洞

请查看 我们的安全策略，了解如何报告安全漏洞。

#鸣谢

• Spatie
• 所有贡献者

#许可证

MIT 许可证 (MIT)。有关更多信息，请参阅 许可证文件。