PHPackages                             noir4y/laravel-root-cause - 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. noir4y/laravel-root-cause

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

noir4y/laravel-root-cause
=========================

Deterministic root-cause diagnostics for Laravel applications.

v0.2.4(3mo ago)01MITPHPPHP ^8.2CI passing

Since Mar 15Pushed 3mo agoCompare

[ Source](https://github.com/noir4y/laravel-root-cause)[ Packagist](https://packagist.org/packages/noir4y/laravel-root-cause)[ Docs](https://github.com/noir4y/laravel-root-cause)[ RSS](/packages/noir4y-laravel-root-cause/feed)WikiDiscussions main Synced 3w ago

READMEChangelog (7)Dependencies (20)Versions (8)Used By (0)

Laravel Root Cause
==================

[](#laravel-root-cause)

Deterministic root-cause diagnostics for Laravel failures.

Laravel Root Cause turns requests, validation failures, exceptions, and query pathologies into reproducible diagnoses with structured JSON output. It is built for cases where you want a deterministic answer, not a generic observability dashboard.

Why This Exists
---------------

[](#why-this-exists)

Telescope is broad observability. Debugbar is a local debugging UI. Ray is a workflow-friendly inspector. Laravel Root Cause is narrower: it classifies the failure, explains why it matched, and exports AI-consumable JSON with candidate fixes.

ToolBest forOutputTelescopeWide framework observabilityUI-heavy trace inspectionDebugbarLocal page-level debuggingBrowser overlay and debug panelsRayFast feedback in your workflowInteractive developer consoleLaravel Root CauseDeterministic diagnosis of a failing requestCLI summary + structured JSONTry It In 3 Minutes
-------------------

[](#try-it-in-3-minutes)

```
composer require noir4y/laravel-root-cause
php artisan root-cause:install
# trigger one failing or pathological request first
php artisan root-cause:trace latest
php artisan root-cause:export latest --format=json
```

The package auto-registers request collection for the `web` and `api` groups by default. Collection is enabled automatically in `APP_ENV=local` and stays off elsewhere until you set `ROOT_CAUSE_ENABLED=true`. Traces are written to `storage/app/root-cause`.

For Users
---------

[](#for-users)

If you are adopting the package in an application, start with the install and export flow in [Try It In 3 Minutes](#try-it-in-3-minutes).

Use these docs as the canonical follow-up:

- [Quickstart](docs/quickstart.md) for install and first diagnosis flow
- [JSON contract](docs/json-contract.md) for stable machine-readable fields
- [Production safety](docs/production-safety.md) for non-local environments

What The Output Looks Like
--------------------------

[](#what-the-output-looks-like)

CLI diagnosis:

```
Trace: trc_validation_failure
Root cause: validation_contract_mismatch
Confidence: 0.76

Summary: Error 422 occurred due to a mismatch between StoreUserRequest and payload.

Evidence
- StoreUserRequest failed on email.required
- Payload keys: [name]
- Route: users.store / Controller: App\Http\Controllers\UserController@store

Suggested fix
- Include the required field "email" in the request payload or make the rule nullable.
- Review StoreUserRequest to confirm the expected payload keys still match the frontend contract.

Repro
- {"method":"POST","uri":"/users","route_name":"users.store","payload_keys":["name"]}

```

JSON export:

```
{
  "trace_id": "trc_exception",
  "diagnosis": {
    "root_cause_category": "unhandled_exception",
    "confidence": 0.62,
    "candidate_fixes": [
      "Inspect the first application frame and add a focused regression test for RuntimeException."
    ]
  }
}
```

Screenshots:

[![Terminal diagnosis](docs/assets/terminal-diagnosis.svg)](docs/assets/terminal-diagnosis.svg)

[![JSON export](docs/assets/json-export.svg)](docs/assets/json-export.svg)

Public Docs
-----------

[](#public-docs)

- [Quickstart](docs/quickstart.md)
- [JSON contract](docs/json-contract.md)
- [Production safety](docs/production-safety.md)
- [Validation failure incident](docs/incidents/validation-failure.md)
- [Exception incident](docs/incidents/exception.md)
- [Query pathology incident](docs/incidents/query-pathology.md)
- [v0.2.0 release notes](docs/releases/v0.2.0.md)
- Demo app: [`examples/laravel12-demo`](examples/laravel12-demo)It reproduces the same incident classes locally; canonical snapshots live under `docs/incidents`.

Commands
--------

[](#commands)

```
php artisan root-cause:trace latest
php artisan root-cause:failed-request
php artisan root-cause:query-pathology
php artisan root-cause:export latest --format=json
php artisan root-cause:prune --days=7
```

For Contributors
----------------

[](#for-contributors)

```
composer install
composer check
```

Optional Git hooks:

```
composer hooks:install
```

Local Git hooks live in `.githooks/`. Run `composer hooks:install` only if you want local commits to execute `composer lint`, `composer analyse`, and `composer test` before the commit is created.

Data Model
----------

[](#data-model)

Each stored artifact is a `TraceEnvelope` containing:

- entrypoint metadata
- sanitized request context
- normalized signals
- a deterministic `DiagnosisReport`

The JSON export compatibility policy for downstream tooling is documented in [JSON contract](docs/json-contract.md).

###  Health Score

34

—

LowBetter than 75% of packages

Maintenance82

Actively maintained with recent releases

Popularity1

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity41

Maturing project, gaining track record

 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

Every ~2 days

Total

7

Last Release

90d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/79f937836cdd258fa1d1b2e93b825eb53e3ef3ba5fad7e090fe57736123e091c?d=identicon)[noir](/maintainers/noir)

---

Top Contributors

[![noir4y](https://avatars.githubusercontent.com/u/210010039?v=4)](https://github.com/noir4y "noir4y (24 commits)")

---

Tags

artisandebuggingdiagnosticslaravelphprequest-tracingphpjsonlaravelaidebuggingexception handlingobservabilitydiagnosticsdeveloper-toolsroot-cause-analysis

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/noir4y-laravel-root-cause/health.svg)

```
[![Health](https://phpackages.com/badges/noir4y-laravel-root-cause/health.svg)](https://phpackages.com/packages/noir4y-laravel-root-cause)
```

###  Alternatives

[larastan/larastan

Larastan - Discover bugs in your code without running it. A phpstan/phpstan extension for Laravel

6.4k51.0M7.6k](/packages/larastan-larastan)[psalm/plugin-laravel

Psalm plugin for Laravel

3345.1M337](/packages/psalm-plugin-laravel)[laravel/mcp

Rapidly build MCP servers for your Laravel applications.

76518.2M120](/packages/laravel-mcp)[laravel/ai

The official AI SDK for Laravel.

9782.1M162](/packages/laravel-ai)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9742.3M121](/packages/roots-acorn)[calebdw/larastan

Larastan - Discover bugs in your code without running it. A phpstan/phpstan extension for Laravel

15104.9k4](/packages/calebdw-larastan)

PHPackages © 2026

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