README

Ignition 是一个美观且可定制的PHP应用错误页面

以下是如何注册ignition的一个最小示例。

use Spatie\Ignition\Ignition;

include 'vendor/autoload.php';

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

现在让我们在一个网络请求期间抛出一个异常。

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()
    ->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，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，只需调用 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();

这将替换所有名为 "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 异常

蝴蝶团队 / ignition

维护者

详细信息