README

Turn Laravel exceptions into two things, automatically:

1. A dev message — what broke, where, and a suggested fix, grounded in your actual stack trace and code.
2. A user message — a calm, non-technical sentence safe to show on your 500 page.

Bring your own LLM key (OpenAI, Anthropic), point OpenAI at an OpenAI-compatible endpoint, or run fully local with Ollama. Output in any language.

Install

composer require kolakachi/laravel-error-explainer
php artisan vendor:publish --tag=error-explainer-config

Set your driver and key in .env:

ERROR_EXPLAINER_DRIVER=openai
OPENAI_API_KEY=sk-...
ERROR_EXPLAINER_LANGUAGE=English   # or French, Yoruba, Portuguese... null follows app locale

That's it. The package hooks your exception handler via reportable(). When an exception is reported in an enabled environment, the explanation is generated (cached by error signature) and written to your log. In queue mode the package serializes a scrubbed payload and dispatches a real queued job instead of blocking the request:

[error-explainer] App\Exceptions\PaymentFailed {"dev_message":"...","user_message":"..."}

In sync mode, the current explanation is also shared with the view layer by default:

• errorExplainerExplanation
• errorExplainerUserMessage

If you want the package to render its own simple HTML error page for server-side exceptions, enable:

ERROR_EXPLAINER_RENDER_ERROR_PAGE=true

The built-in page can also show the developer explanation while APP_DEBUG=true, or you can force it on with:

ERROR_EXPLAINER_SHOW_DEV_PANEL=true

Manual use

use Kolakachi\ErrorExplainer\Facades\ErrorExplainer;

try {
    $charge->process();
} catch (Throwable $e) {
    $explanation = ErrorExplainer::explain($e);

    return response()->view('errors.friendly', [
        'message' => $explanation?->userMessage ?? __('Something went wrong.'),
    ], 500);
}

Error Page Integration

For a custom Laravel error page, you can render the current safe message with the built-in component:

<x-error-explainer-user-message
    class="text-sm text-gray-600"
    fallback="Something went wrong. Please try again."
/>

You can also read the shared view data directly if you prefer:

{{ $errorExplainerUserMessage ?? __('Something went wrong.') }}

With ERROR_EXPLAINER_RENDER_ERROR_PAGE=true, the package can also return its own built-in HTML error page for non-JSON 5xx responses. The page renders even when no explanation is available (for example in production, where explanations are gated off, or if the LLM call fails) — it falls back to the view.fallback_message config value and hides the developer panel. So you can use it as a plain branded 500 page and let the AI message fill in wherever explanations run.

Custom LLM providers

use Kolakachi\ErrorExplainer\Facades\ErrorExplainer;
use Kolakachi\ErrorExplainer\Contracts\LlmDriver;

ErrorExplainer::llm()->extend('gemini', fn ($app) => new class implements LlmDriver {
    public function complete(string $systemPrompt, string $userPrompt): string
    {
        // your HTTP call here
    }
});

Then set ERROR_EXPLAINER_DRIVER=gemini.

If your provider exposes an OpenAI-compatible API, you can often use the built-in openai driver instead:

ERROR_EXPLAINER_DRIVER=openai
OPENAI_API_KEY=...
ERROR_EXPLAINER_OPENAI_MODEL=openai/gpt-4o-mini
ERROR_EXPLAINER_OPENAI_BASE_URL=https://openrouter.ai/api/v1

Privacy

Before anything is sent to a provider, the payload passes through a regex scrubber (scrub_patterns in config) that redacts passwords, bearer tokens, API keys, and emails by default. Add your own patterns. For zero data egress, use the ollama driver — inference stays on your machine.

Cost control

Explanations are cached by exception signature (class + file + line + normalized message), so an exception firing 10,000 times in a hot loop costs you one LLM call. Numeric IDs in messages are normalized, so User 42 not found and User 99 not found share a cache entry.

Filtering

Skip noisy or intentional exceptions with except, and by default anything implementing Laravel's ShouldntReport contract is ignored automatically:

// config/error-explainer.php
'except' => [
    App\Exceptions\ExpectedApiException::class,
],

Testing

Built for Orchestra Testbench + Pest:

composer test

License

MIT