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.1.1(1mo ago)01↓100%MITPHPPHP ^8.2CI passing Since Mar 15Pushed 1mo agoCompare [ Source](https://github.com/noir4y/laravel-root-cause)[ Packagist](https://packagist.org/packages/noir4y/laravel-root-cause)[ RSS](/packages/noir4y-laravel-root-cause/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (5)Dependencies (10)Versions (3)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 35 — LowBetter than 79% of packages Maintenance89 Actively maintained with recent releases Popularity2 Limited adoption so far Community6 Small or concentrated contributor base Maturity37 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 Every ~0 days Total 2 Last Release 58d 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 (19 commits)") --- Tags artisandebuggingdiagnosticslaravelphprequest-tracing ### 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.4k43.5M5.2k](/packages/larastan-larastan)[laravel/passport Laravel Passport provides OAuth2 server support to Laravel. 3.4k85.0M532](/packages/laravel-passport)[laravel/cashier Laravel Cashier provides an expressive, fluent interface to Stripe's subscription billing services. 2.5k25.9M107](/packages/laravel-cashier)[roots/acorn Framework for Roots WordPress projects built with Laravel components. 9682.1M97](/packages/roots-acorn)[laravel/pulse Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application. 1.7k12.1M99](/packages/laravel-pulse)[aedart/athenaeum Athenaeum is a mono repository; a collection of various PHP packages 255.2k](/packages/aedart-athenaeum) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)