PHPackages                             kolakachi/laravel-error-explainer - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Debugging & Profiling](/categories/debugging)
4. /
5. kolakachi/laravel-error-explainer

ActiveLibrary[Debugging & Profiling](/categories/debugging)

kolakachi/laravel-error-explainer
=================================

Turn Laravel exceptions into dev-friendly explanations and user-safe messages using your own LLM keys. Multi-provider, multi-language.

v0.1.0(1mo ago)00MITPHPPHP ^8.2CI failing

Since Jul 7Pushed 1mo agoCompare

[ Source](https://github.com/kolakachi/laravel-error-explainer)[ Packagist](https://packagist.org/packages/kolakachi/laravel-error-explainer)[ RSS](/packages/kolakachi-laravel-error-explainer/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (8)Versions (2)Used By (0)

Laravel Error Explainer
=======================

[](#laravel-error-explainer)

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
-------

[](#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
----------

[](#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
----------------------

[](#error-page-integration)

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

```

```

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
--------------------

[](#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
-------

[](#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
------------

[](#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
---------

[](#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
-------

[](#testing)

Built for Orchestra Testbench + Pest:

```
composer test
```

License
-------

[](#license)

MIT

###  Health Score

34

—

LowBetter than 74% of packages

Maintenance90

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity36

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

49d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/32527d18d4a6bb72a609f9e91969214943f26df2614057c8a03b6608415b1f31?d=identicon)[kolakachi](/maintainers/kolakachi)

---

Top Contributors

[![kolakachi](https://avatars.githubusercontent.com/u/20257188?v=4)](https://github.com/kolakachi "kolakachi (3 commits)")

---

Tags

laravelaidebuggingexceptionserror handlingllm

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/kolakachi-laravel-error-explainer/health.svg)

```
[![Health](https://phpackages.com/badges/kolakachi-laravel-error-explainer/health.svg)](https://phpackages.com/packages/kolakachi-laravel-error-explainer)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3345.4M354](/packages/psalm-plugin-laravel)[laravel/mcp

Rapidly build MCP servers for your Laravel applications.

80427.1M249](/packages/laravel-mcp)[propaganistas/laravel-disposable-email

Disposable email validator

6023.2M7](/packages/propaganistas-laravel-disposable-email)[laravel/pulse

Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application.

1.7k16.3M158](/packages/laravel-pulse)[api-platform/laravel

API Platform support for Laravel

58190.1k21](/packages/api-platform-laravel)[defstudio/telegraph

A laravel facade to interact with Telegram Bots

818355.4k3](/packages/defstudio-telegraph)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)