README

composer require isaidgitmenow/laravel-errors

A powerful, elegant, and declarative error handling package for modern Laravel applications (Laravel 11+).

Built with PHP 8.4+ Attributes and strictly adhering to SOLID principles, this package replaces traditional, boilerplate-heavy exception rendering and reporting methods with clean, declarative attributes directly on your Exception classes.

✨ Features

Declarative PHP 8 Attributes: Configure HTTP codes, reporting rules, rate limiting, and context directly on your exception classes.
Plug-and-Play Frontend Integrations: Automatically detects the context of the request (Filament, Livewire, Inertia, API, Web) and formats the response appropriately so your SPA or Admin panel doesn't break on a 500 error.
Bulletproof Resilience: Includes a self-healing try/catch wrapper so an error in your error handler never causes a White Screen of Death (WSOD).
Deep Attribute Inspection: Safely traverses Laravel's wrapped exceptions (e.g., QueryException, ViewException) to find and apply your custom attributes on the original exception.
Spatie Ignition & Laravel Debugbar Ready: Seamlessly integrates with local developer tools without breaking production flows.
Xdebug IDE Enrichment: Push sanitized #[WithContext] payloads directly to your IDE as debug notifications.
Auto-Injection into Laravel Context: Automatically forwards #[WithContext] data to downstream trackers like Sentry or Flare via Laravel 11's global Context.
Data Sanitization: Built-in redaction for sensitive keys (like passwords and API tokens) before they hit logs or external trackers.
Anti-Spam Rate Limiting: Prevent cascading failures from exhausting your error tracker quotas using the #[RateLimit] attribute.
Octane Compatible: Automatically flushes the reflection cache and dynamic state after every request under Swoole / RoadRunner to prevent memory leaks.
Dynamic Pass-Through: Third-party packages can register exceptions to bypass the pipeline at runtime — no config edits required.
Fallback Logging: Ensures your application never runs completely blind by falling back to Laravel's default logger if no reporters are configured — whether via config or dynamically via addReporter().
Environment-Specific Reporting: Restrict #[ReportTo] to specific environments (e.g., only send Slack alerts in production).
make:error Artisan Command: Scaffold fully decorated exception classes in seconds with php artisan make:error.
Static Analysis Ready: Ships with a phpstan.neon.dist pre-configured for Larastan level 5.
MCP Server Built-in: Includes a native Model Context Protocol (MCP) server so your AI agent can create, inspect, and simulate errors straight from your IDE.
CI/CD Ready: Includes a GitHub Actions workflow matrix covering PHP 8.4/8.5 × Laravel 11/12.

📦 Requirements

PHP 8.4+
Laravel 11.0+

🚀 Installation & Setup

You can install the package via composer:

composer require isaidgitmenow/laravel-errors

Optionally, publish the configuration file to customize the pipeline:

php artisan vendor:publish --tag="laravel-errors-config"

Integration is incredibly simple. Open your bootstrap/app.php and register the handler:

// bootstrap/app.php
use Illuminate\Foundation\Configuration\Exceptions;
use Isaidgitmenow\LaravelErrors\ErrorHandler;

return Application::configure(basePath: dirname(__DIR__))
    // ...
    ->withExceptions(function (Exceptions $exceptions) {
        // Let the package orchestrate your entire error pipeline:
        ErrorHandler::handle($exceptions);
    })->create();

📚 Documentation

For detailed usage and advanced configuration, please refer to the specific documentation chapters:

Core Architecture And Api

🏗️ Core Architecture & API Reference
🕵️‍♂️ How Does It Know the Request Context?
🚀 The Complete Lifecycle: Generating, Throwing & Logging

Usage And Attributes

📖 Usage: The Attributes API
💡 The Ultimate Exception Example
🤔 Do I Still Need try/catch?

Renderers

🎨 Context Detectors & Renderers
🌐 Web Renderer Example
📡 API Renderer Example
⚡ Livewire Renderer Example
🛡️ Filament Renderer Example
⚛️ Inertia.js Renderer Example

Reporters And Integrations

📢 Reporters
💬 Slack Integration Example
🦉 NightWatch Integration Example
💥 Flare (or Sentry) Integration
🐛 Laravel Debugbar Integration Example
🐞 Xdebug IDE Enrichment
🔀 Routing to Different Log Channels
🌍 Environment-Specific Reporting

Exception Handling Mechanics

🚧 Bypassing the Pipeline: Native Laravel Exceptions
🚦 The "Pass Through" Exceptions (Complete List)
🤷‍♂️ Handling Generic (Un-decorated) Exceptions
📝 A Note on API Form Requests (ValidationException)
🛡️ Working with Gates & Permissions (AuthorizationException)
🌍 Translated Error Messages Example

Advanced Configuration And Patterns

⚙️ Advanced Configuration & Mechanics
🧩 Custom Detectors, Renderers, and Reporters
🏗️ Building a Custom Detector (Step-by-Step)
🛑 Anti-Spam: Error Rate Limiting (In-Depth)
⚡ Performance & Error Cache (Octane / Testing)
🤯 Exotic Use Cases & Advanced Patterns
🌐 Advanced API: Complying with JSON:API Specification

Ecosystem And Commands

⚙️ Queue Jobs Integration
💻 Artisan Commands Integration
🛠️ Generating Exceptions: make:error
🏗️ Domain Driven Design (DDD) Support

Testing And Ci

🧪 Testing Your Application
🔬 Static Analysis with Larastan
🤖 Continuous Integration (GitHub Actions)

🤖 AI Agent Integration (MCP Server)

This package ships with a native Model Context Protocol (MCP) server, meaning your favorite AI coding assistant (like Claude Desktop, Cursor, or Antigravity) can connect directly to your local error pipeline.

With the MCP integration enabled, your AI can:

Generate Exceptions: Ask your AI to "Create a PaymentFailed error with a 402 status that reports to Slack", and it will use the MCP tool to generate the fully decorated file.
Inspect Pipeline: The AI can query your active Detectors, Renderers, and Reporters.
Search Logs: The AI can query your application's historical JSONL error logs directly to help you debug past errors.
Simulate Errors: The AI can instantiate and run exceptions through the pipeline in a rolled-back transaction to verify how they behave.

Setup

To connect your AI agent, add the following configuration to your client's mcp_config.json (or claude_desktop_config.json):

{
  "mcpServers": {
    "laravel-errors-mcp": {
      "command": "cmd",
      "args": [
        "/c",
        "cd /path/to/your/project && php artisan errors:mcp"
      ]
    }
  }
}

(If you are on Linux or macOS, simply use bash and -c instead of cmd and /c)

🧪 Testing

The package includes a comprehensive test suite (built with Pest and Orchestra Testbench).

composer test

Run static analysis with Larastan:

composer phpstan

📜 License

This package is Dual Licensed:

Open Source (GPLv3): Free for personal or open-source projects. If you use this package, your application must also be open-source under the GPLv3.
Commercial Use: If you are building a commercial, proprietary, or closed-source application, you must purchase a Commercial License.

Purchase a License

To purchase a Commercial License, please visit unicweb.ro or contact lucian.laravel@gmail.com for inquiries.

Please read the full LICENSE Agreement for complete details.

isaidgitmenow / laravel-errors

Maintainers

Package info

Statistics

Security