README

Laravel 12–13 package to automatically send detailed exception reports to configured email addresses. Features a clean HTML template that includes your application's name and environment, full stack traces, comprehensive context data with automatic sensitive data masking, and built-in rate limiting to prevent spamming your inbox when your application throws repeated errors.

✨ Features

Clean HTML Template: A clear and readable layout for error reporting.
Comprehensive Context Capture:
- Web Requests: URL, Method, User info, Request Body (including safe metadata for uploaded files), Headers, Cookies, and $_SERVER array.
- Console Commands (CLI): Command arguments and $_SERVER array.
Automatic Sensitive Data Masking: Redacts passwords, tokens, API keys, authorization headers, cookies, and secret environment variables (APP_KEY, DB_PASSWORD, etc.) with ********.
Rate Limiting: Protects your inbox from spam when a recurring error floods your application, with graceful fallback if your cache backend is unavailable.
Exception Filtering: Configure a list of ignored exception classes (including parent classes/interfaces) that should not trigger email notifications.
Smart Email Subjects: The error message is automatically normalized and appended to the email subject line (and truncated if too long), making it easy to identify the error at a glance. An optional short hash can be enabled to group similar errors.
Previous Exceptions: Automatically unwraps and displays previous exceptions in the chain.

📋 Requirements

PHP 8.2+
Laravel 12.x–13.x

📦 Installation

You can install the package via composer:

composer require artryazanov/laravel-error-mailer

Laravel auto-discovers the service provider. No manual registration is needed.

⚙️ Configuration

Publish the configuration and view files to customize them:

php artisan vendor:publish --tag="error-mailer-config"
php artisan vendor:publish --tag="error-mailer-views"

Configuration file: config/error-mailer.php

In your .env file, you can set the following variables:

ERROR_MAILER_ENABLED=true
ERROR_MAILER_FROM=error-mailer@example.com
ERROR_MAILER_TO=admin@example.com
ERROR_MAILER_CC=
ERROR_MAILER_BCC=
# Optional: Override the default subject "Error on {APP_NAME}"
# The exact error message is automatically appended to the subject in either case.
ERROR_MAILER_SUBJECT="Error on production"

# Optional: Append a hash of the exception message to the subject (useful for email clients grouping). Defaults to false.
ERROR_MAILER_INCLUDE_HASH_IN_SUBJECT=false

# Optional: Custom Blade view and queue name
ERROR_MAILER_VIEW="error-mailer::emails.exception"
ERROR_MAILER_QUEUE=default

# Rate limit: Max emails to send per time window (in seconds). Set ERROR_MAILER_LIMIT=0 to disable.
ERROR_MAILER_LIMIT=15
ERROR_MAILER_WINDOW=3600

# Maximum number of stack trace frames captured per exception
ERROR_MAILER_TRACE_MAX_FRAMES=100

Ignoring Specific Exceptions

In config/error-mailer.php, you can specify exception classes (or base classes/interfaces) that should never be emailed:

'ignore' => [
    \Symfony\Component\HttpKernel\Exception\NotFoundHttpException::class,
    \Illuminate\Validation\ValidationException::class,
],

Sensitive Data Masking

By default, the package masks fields matching password, password_confirmation, current_password, secret, token, api_key, access_token, refresh_token, authorization, cookie, x-api-key, x-csrf-token, x-xsrf-token, php-auth-pw, app_key, credit_card, card_number, cvv, as well as any key ending in _password, _secret, _key, or _token.

You can customize the hidden_parameters array in config/error-mailer.php to add your own application-specific sensitive keys.

💻 Usage

Laravel 11+

In newer Laravel versions, exception handling is configured in bootstrap/app.php. Add the explicit reporting callback inside your withExceptions method:

use Artryazanov\ErrorMailer\Facades\ErrorMailer;
use Illuminate\Foundation\Configuration\Exceptions;
use Throwable;

return Application::configure(basePath: dirname(__DIR__))
    // ...
    ->withExceptions(function (Exceptions $exceptions) {
        $exceptions->reportable(function (Throwable $e) {
            ErrorMailer::handle($e);
        });
    })->create();

Older Laravel Versions (or custom Handlers)

If you are using app/Exceptions/Handler.php, you can call the facade in your register method:

use Artryazanov\ErrorMailer\Facades\ErrorMailer;
use Throwable;

public function register(): void
{
    $this->reportable(function (Throwable $e) {
        ErrorMailer::handle($e);
    });
}

🛡️ Rate Limiting

If your application loses connection to a database or a critical service goes down, it might throw hundreds of exceptions per minute.

This package has built-in Rate Limiting to protect your inbox. By default, it allows sending 15 emails per hour. Any exceptions thrown beyond this limit will be suppressed from the mailer (but a standard Laravel Log::warning will be recorded stating that the email was suppressed).

You can tweak the threshold in your .env using ERROR_MAILER_LIMIT and ERROR_MAILER_WINDOW (or set ERROR_MAILER_LIMIT=0 to disable rate limiting).

🧪 Testing & Local Preview

Running Automated Tests & Quality Checks

# Run PHPUnit test suite
composer test

# Run PHPUnit with code coverage report
composer test-coverage

# Check code style with Laravel Pint
composer lint

# Run static analysis with PHPStan / Larastan
composer analyse

Email Preview with Mailpit

If you want to see exactly how the generated emails look without deploying to a live server, this package includes a convenient Docker-based preview script using Mailpit.

Start the Mailpit Docker container:
```
docker compose up -d
```
Run the preview script to simulate an exception and send the email:
```
php preview-docker.php
```
Open your browser and navigate to http://localhost:18025 to view the rendered HTML email in Mailpit's web interface.

🎨 Customizing the View

If you published the views, you can find the HTML email template in resources/views/vendor/error-mailer/emails/exception.blade.php. You can modify it to match your company's branding, adjust the layout, or include additional variables.

📄 License

This package is released under the MIT License. See LICENSE for details.

artryazanov / laravel-error-mailer

Package info

Security

Statistics