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。

对于所有其他 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();

屏蔽请求体字段

当网络请求中出现异常时，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的用户界面进行工作，则需要执行以下步骤。

将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异常

安全漏洞

有关如何报告安全漏洞的更多信息，请参阅我们的安全策略。

鸣谢

许可

MIT许可（MIT）。有关更多信息，请参阅许可文件。

dyanakiev-forks / ignition74

维护者

详细信息