README

Stop wrestling with bootstrap/app.php and bloated Exception classes. Laravel Errors completely reimagines exception handling in Laravel 11+ using PHP 8.4 Attributes.

Instead of writing custom render() and report() methods for every exception, or cluttering your global handler with complex if ($e instanceof ...) logic, you can now define how an exception behaves declaratively:

use Isaidgitmenow\LaravelErrors\Attributes\HttpCode;
use Isaidgitmenow\LaravelErrors\Attributes\ReportTo;
use Isaidgitmenow\LaravelErrors\Attributes\RateLimit;

#[HttpCode(402)]
#[ReportTo(['slack', 'sentry'])]
#[RateLimit(max: 5, intervalInMinutes: 1)]
class PaymentFailedException extends Exception
{
    // That's it! No render(), no report() methods.
}

🚀 Why adopt this package today?

Zero Boilerplate: Ditch the massive render and report methods. Your exceptions become clean, SOLID-compliant data structures.
Context-Aware Rendering: Throw an error anywhere. The package automatically detects if the request is from Livewire, Filament, Inertia, an API, or Web, and formats the response perfectly so your frontend doesn't break.
Save Your Error Quotas: Native Rate Limiting (#[RateLimit]) prevents error spikes from exhausting your Sentry/Flare limits.
Automatic Context Injection: Attach data via #[WithContext] and it flows automatically into Laravel's global Context, your logs, and your bug trackers.
Privacy Built-in: Use #[Sensitive] to automatically redact passwords and API keys before they hit your logs.

composer require isaidgitmenow/laravel-errors

✨ 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.
RFC 9457 Problem Details: The API Renderer automatically formats errors according to the IETF RFC 9457 standard (Problem Details for HTTP APIs).
ULID Error Identities: Every error automatically generates a unique, sortable ULID (ErrorIdentity) that is injected into logs and the API response for exact tracing.
Auto-Injection into Laravel Context: Automatically forwards #[WithContext] data to downstream trackers like Sentry or Flare via Laravel 11's global Context.
Deep Data Masking (Masker): Built-in redaction for sensitive keys using the #[Sensitive] attribute (supports first_last, last4, email, hash, and length masking) 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.
Critical Fallback Logging (CriticalLog): Ensures your application never runs completely blind. If all reporters fail or none are configured, it writes to a dedicated storage/logs/errors-critical.log.
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

The MIT License (MIT). Please see License File for more information.

isaidgitmenow / laravel-errors

Package info

Security

Statistics