README

Send Laravel exception emails with the message, request URL, IP address, and stack trace.

Table of Contents

• Laravel Support
• Requirements
• Installation
• Quick Start
• Laravel 11 through 13
• Laravel 9 and 10, or an existing Handler class
• Features
• Configuration
• Changing Email Layouts
• Dark Mode
• Custom Views
• Artisan Commands
• Install and Update Options
• Safe Updates
• Testing
• License

Laravel Support

The existing standalone Blade email remains the default. composer update does not publish files, switch layouts, modify application settings, or register an exception reporting callback. Existing customized mailers and views continue to work.

The current package retains its ^8.0 PHP constraint. Laravel determines the application's minimum PHP version. Historical compatibility testing does not extend Laravel's upstream security support.

See upgrading, historical installation, and compatibility decisions.

Requirements

• PHP and Laravel versions from the table above.
• A configured Laravel mail transport and at least one recipient.

Both email layouts render with self-contained styles. Applications do not need frontend assets or an npm build to send them.

Installation

composer require jeremykenedy/laravel-exception-notifier
php artisan exception-notifier:install

Laravel discovers the provider automatically. The command detects existing files and preserves them. Choose keep to retain the current email or install the legacy view when none exists. An explicit selection offers the legacy or modern layout and a light, dark, or system theme.

For unattended installation using the existing defaults:

php artisan exception-notifier:install --no-interaction

The original publish command remains supported:

php artisan vendor:publish --tag=laravelexceptionnotifier

Both approaches create these files when missing:

• app/Mail/ExceptionOccurred.php
• resources/views/emails/exception.blade.php
• config/exceptions.php

Quick Start

Configure your application's mail transport, then set the recipients in .env:

EMAIL_EXCEPTION_ENABLED=true
EMAIL_EXCEPTION_FROM=errors@example.com
EMAIL_EXCEPTION_TO="developer@example.com,operations@example.com"
EMAIL_EXCEPTION_CC=
EMAIL_EXCEPTION_BCC=
EMAIL_EXCEPTION_SUBJECT="Production exception"
EMAIL_EXCEPTION_THEME=light

Register exception reporting using the instructions for your Laravel application below. Installation does not send a test message or register the callback automatically.

Laravel 11 through 13

Add a report callback to your existing withExceptions block in bootstrap/app.php:

use App\Mail\ExceptionOccurred;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\Mail;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->report(function (\Throwable $exception): void {
        if (! config('exceptions.emailExceptionEnabled')) {
            return;
        }

        try {
            Mail::send(new ExceptionOccurred([
                'message' => $exception->getMessage(),
                'file' => $exception->getFile(),
                'line' => $exception->getLine(),
                'trace' => $exception->getTrace(),
                'url' => request()->url(),
                'body' => request()->all(),
                'ip' => request()->ip(),
            ]));
        } catch (\Throwable $mailException) {
            Log::error($mailException);
        }
    });
})

Laravel's ignored exception rules still apply. The callback does not stop normal logging. Add it once to avoid duplicate emails, and keep any existing reporting callbacks.

Laravel 9 and 10, or an existing Handler class

In app/Exceptions/Handler.php, register the same callback with $this->reportable(...) inside register(). Keep your existing dontReport rules and callbacks. Applications already using sendEmail() or ExceptionNotificationHandlerTrait can keep them unchanged.

The trait source is available at src/App/Traits/ExceptionNotificationHandlerTrait.php for applications that already copy it. It is not automatically loaded into the application's App namespace or installed over an existing Handler.

Features

• Exception messages, request details, and stack traces in email.
• Multiple recipients with optional CC and BCC.
• Original and modern Blade email layouts.
• Light, dark, and system themes.
• Safe installation and layout updates with view backups.
• Custom mailers, views, and existing configuration remain application-owned.

Configuration

Settings live in config/exceptions.php. Existing keys and defaults are preserved.

Changing Email Layouts

Run the update command for an interactive layout selection:

php artisan exception-notifier:update

Existing views require --force for an explicit replacement. The command saves a unique adjacent .bak copy before changing the view. Configuration and mailer files are preserved.

php artisan exception-notifier:update --layout=modern --theme=system --force
php artisan view:clear

To restore the original layout:

php artisan exception-notifier:update --layout=legacy --theme=light --force
php artisan view:clear

Dark Mode

light stays light, dark renders dark colors directly, and system follows prefers-color-scheme where the email client supports it. Email clients can override colors. Clients without media query support use the light fallback for system.

An explicit theme selection is saved in the installed view wrapper. To follow configuration instead, use this in your email view:

@include('laravelexceptionnotifier::emails.modern')

Then set emailExceptionTheme in config/exceptions.php to env('EMAIL_EXCEPTION_THEME', 'light'). Older published config files need this entry added manually.

Custom Views

exceptions.emailExceptionView continues to select the mailable's view. Set it to your own Blade view or laravelexceptionnotifier::emails.modern. The $content array is unchanged. The commands only manage resources/views/emails/exception.blade.php; a custom view setting takes precedence and is never rewritten.

Laravel's standard namespaced overrides under resources/views/vendor/laravelexceptionnotifier/emails/ also work. Exception values are escaped, and the included templates omit request bodies and stack arguments.

Artisan Commands

Install and Update Options

Safe Updates

composer update jeremykenedy/laravel-exception-notifier
php artisan exception-notifier:update --no-interaction

The update command restores missing files and preserves existing files. Even --force alone does not reset a view. A replacement requires a layout selection plus --force. Configuration and mailer files are never overwritten by these commands.

After changing views or configuration, use your normal deployment cache workflow, for example:

php artisan view:clear
php artisan config:cache

See the upgrade guide for published mailer changes and rollback steps.

Testing

composer install
composer test
composer lint
composer audit

npm ci --ignore-scripts
npx playwright install chromium
npm run test:browser

PHPUnit covers publishing, configuration, recipients, rendering and in-memory mail delivery, throwable reporting, delivery failures, escaping, themes, and command upgrades. Browser tests cover mobile and desktop rendering, long text, system theme changes, and accessibility of the modern layout. Tests use generated sample data and do not send external mail.

CI tests Laravel 9 through 13 on their supported PHP combinations, plus the lowest dependencies on PHP 8.0 and a pinned Laravel 9.20 mail-delivery regression. Browser tests, lint, audits, and a coverage report run on the current stack. Node and npm are development tools for browser testing only. See testing details.

License

This package is open-sourced software licensed under the MIT license.