README

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。

对于 Drupal 10+ 网站，使用 Ignition 模块。

对于 OpenMage 网站，使用 Ignition 模块。

对于所有其他 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()
    ->setTheme('dark')
    ->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',
        ];
    }
}

如果您抛出异常，它将这样显示。

使用解决方案提供者

除了直接将解决方案添加到异常中，您还可以创建一个解决方案提供者。当异常返回解决方案时，解决方案提供者允许您确定异常是否可以解决。

例如，您可以创建一个自定义的“堆栈溢出解决方案提供者”，该提供者将检查是否存在针对给定可抛出对象的解决方案。

解决方案提供者可以通过第三方包或在您的应用程序内部添加。

解决方案提供者是任何实现 \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，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)

提示应用程序类型

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

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

$aiSolutionProvider->applicationType('WordPress 6.2')

将异常发送到 Flare

Ignition 内置了将异常发送到 Flare 的功能，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();

屏蔽请求数据字段

当网络请求中出现异常时，Flare 客户端会将请求体中存在的任何请求字段传递下去。

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

要屏蔽某些字段的值，您可以使用 censorRequestBodyFields。您应该传递要屏蔽的字段名称。

use Spatie\FlareClient\Flare;

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

这将用空值替换任何名为 "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();

变更日志

有关最近更改的更多信息，请参阅变更日志。

贡献

有关详细信息，请参阅贡献指南。

开发设置

如果您想为 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 / ignition

维护者

详情