Spatie Ignition

Ignition can display actionable solutions for errors. There are two ways to implement this:

1. Implementing ProvidesSolution on an Exception

Make your custom exception implement the Spatie\Ignition\Contracts\ProvidesSolution interface. You must implement the getSolution() method, which returns an instance of Spatie\Ignition\Contracts\Solution.

2. Using Solution Providers

For more complex logic (like looking up solutions on Stack Overflow), implement the Spatie\Ignition\Contracts\HasSolutionsForThrowable interface. This allows you to decide if a provider can solve a specific Throwable via canSolve() and then return the solutions via getSolutions().

Register providers using addSolutionProviders().

// Implementing a solution directly in an exception
use Spatie\Ignition\Contracts\Solution;
use Spatie\Ignition\Contracts\ProvidesSolution;

class CustomException extends Exception implements ProvidesSolution
{
    public function getSolution(): Solution
    {
        return new CustomSolution();
    }
}

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',
        ];
    }
}

// Registering a solution provider
\Spatie\Ignition\Ignition::make()
    ->addSolutionProviders([
        YourSolutionProvider::class,
    ])
    ->register();

Ignition can use OpenAI to suggest solutions for exceptions.

1. Install dependency: composer require openai-php/client
2. Instantiate provider: Create an instance of OpenAiSolutionProvider with your OpenAI API key.
3. Register provider: Pass the instance to addSolutionProviders().

Features:

• Context: It sends the error message, class, stack frame, and surrounding context. It excludes request payloads and environment variables for security.
• Caching: Use useCache(CacheInterface $cache, int $cacheTtlInSeconds) on the provider to avoid redundant API calls for similar errors.
• Application Hinting: Use applicationType('Type') (e.g., 'WordPress 6.2') to improve suggestion quality.

composer require openai-php/client

use \Spatie\Ignition\Solutions\OpenAi\OpenAiSolutionProvider;

$aiSolutionProvider = new OpenAiSolutionProvider($openAiKey);
$aiSolutionProvider->applicationType('WordPress 6.2');
$aiSolutionProvider->useCache($cacheInstance, 3600);

\Spatie\Ignition\Ignition::make()
    ->addSolutionProviders([$aiSolutionProvider])
    ->register();

Ignition can send exceptions to Flare.

Basic Setup

Use sendToFlare($apiKey) and runningInProductionEnvironment($boolean) to ensure errors are reported to Flare in production without showing the Ignition UI to users.

Customizing Flare Data

Use configureFlare(callable $callback) to access the Spatie\FlareClient\Flare instance for advanced configuration:

• context($key, $value): Add key-value pairs to every exception.
• group($key, array $data): Group context items together.
• anonymizeIp(): Prevent user IP addresses from being sent.
• censorRequestBodyFields(array $fields): Replace sensitive fields (like password) with <CENSORED>.
• registerMiddleware(array $middleware): Register classes implementing FlareMiddleware to modify the Report before it is sent.

Flare Middleware Example

Implement FlareMiddleware to intercept and modify the Report object.

use Spatie\FlareClient\Flare;
use Spatie\FlareClient\FlareMiddleware\FlareMiddleware;
use Spatie\FlareClient\Report;
use Closure;

// 1. Define Middleware
class MyMiddleware implements FlareMiddleware
{
    public function handle(Report $report, Closure $next)
    {
        $report->message("{$report->getMessage()}, now modified");
        return $next($report);
    }
}

// 2. Register everything
\Spatie\Ignition\Ignition::make()
    ->runningInProductionEnvironment(true)
    ->sendToFlare('YOUR_FLARE_API_KEY')
    ->configureFlare(function(Flare $flare) {
        $flare->context('Tenant', 'My-Tenant-Identifier');
        $flare->censorRequestBodyFields(['password']);
        $flare->registerMiddleware([MyMiddleware::class]);
    })
    ->register();