Filament Error Mailer 🚨

A powerful Filament plugin that provides instant error notifications via email and Discord webhooks, with a beautiful error details page for debugging. Never miss a critical error in your application again!

✨ Key Features

• 📧 Instant Email Notifications - Get notified immediately when errors occur
• 💬 Discord Webhook Integration - Send alerts to your Discord channels
• 🎯 Smart Application File Detection - Automatically identifies errors in your code (excluding vendor files)
• 🌓 Beautiful Error Details Page - Dark/Light mode with copy & share functionality
• ⏱️ Cooldown System - Prevents notification spam for duplicate errors
• 🎛️ Advanced Filtering - Filter by log level, exception type, or environment
• 🔒 Secure Access - Protected by Filament authentication
• 📦 JSON Storage - All errors stored as JSON files for easy access

📋 Table of Contents

• Installation
• Configuration
  • Email Configuration
  • Discord Webhook
  • Error Filtering
  • Cooldown Period
  • Storage Path
• Features in Detail
  • Smart Application File Detection
  • Error Details Page
  • Notification Cooldown
• Usage
  • Accessing Error Details
  • Scheduled Cleanup
• Advanced Configuration
• Contributing
• License

📦 Installation

Step 1: Install via Composer

composer require hugomyb/filament-error-mailer

Step 2: Publish Configuration

Publish the configuration file:

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

This creates config/error-mailer.php with the following default configuration:

return [
    'email' => [
        'recipient' => ['recipient1@example.com'],
        'bcc' => [],
        'cc' => [],
        'subject' => 'An error has occurred - ' . config('app.name'),
    ],

    'disabledOn' => [
        //
    ],

    'cacheCooldown' => 10, // in minutes

    'webhooks' => [
        'discord' => env('ERROR_MAILER_DISCORD_WEBHOOK'),

        'message' => [
            'title' => 'Error Alert - ' . config('app.name'),
            'description' => 'An error has occurred in the application.',
            'error' => 'Error',
            'file' => 'File',
            'line' => 'Line',
            'details_link' => 'See more details'
        ],
    ],

    'storage_path' => storage_path('app/errors'),

    'ignore' => [
        'levels' => [
            // 'debug',
            // 'info',
        ],
        'exceptions' => [
            // \Symfony\Component\HttpKernel\Exception\NotFoundHttpException::class,
        ],
    ],
];

Step 3: Configure Mail Server

⚠️ IMPORTANT: Configure your mail server in .env to receive email notifications:

MAIL_MAILER=smtp
MAIL_HOST=your-smtp-host.com
MAIL_PORT=587
MAIL_USERNAME=your-smtp-username
MAIL_PASSWORD=your-smtp-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@yourapp.com
MAIL_FROM_NAME="${APP_NAME}"

Step 4: Register the Plugin

Add the plugin to your Filament panel provider (e.g., app/Providers/Filament/AdminPanelProvider.php):

use Hugomyb\FilamentErrorMailer\FilamentErrorMailerPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        // ... other configuration
        ->plugins([
            FilamentErrorMailerPlugin::make(),
        ]);
}

Step 5: (Optional) Publish Views

If you want to customize the error details page or email template:

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

---

⚙️ Configuration

Email Configuration

Configure email recipients and subject in config/error-mailer.php:

'email' => [
    'recipient' => ['admin@example.com', 'dev@example.com'],
    'bcc' => ['monitoring@example.com'],
    'cc' => [],
    'subject' => 'Error Alert - ' . config('app.name'),
],

Options:

• recipient (array): Primary email addresses to receive notifications
• bcc (array): Blind carbon copy recipients
• cc (array): Carbon copy recipients
• subject (string): Email subject line (supports dynamic values)

Discord Webhook

Send error notifications to Discord channels:

1. Create a Discord Webhook:

• Go to your Discord server settings
• Navigate to Integrations → Webhooks
• Click "New Webhook"
• Copy the webhook URL

2. Add to .env:

ERROR_MAILER_DISCORD_WEBHOOK="https://discord.com/api/webhooks/your-webhook-id/your-webhook-token"

3. Customize webhook messages (optional):

'webhooks' => [
    'discord' => env('ERROR_MAILER_DISCORD_WEBHOOK'),

    'message' => [
        'title' => 'Error Alert - ' . config('app.name'),
        'description' => 'An error has occurred in the application.',
        'error' => 'Error',
        'file' => 'File',
        'line' => 'Line',
        'details_link' => 'View Details',
    ],
],

Error Filtering

Control which errors trigger notifications:

'ignore' => [
    // Ignore specific log levels
    'levels' => [
        'debug',
        'info',
        // 'warning',
        // 'error',
    ],

    // Ignore specific exception types
    'exceptions' => [
        \Symfony\Component\HttpKernel\Exception\NotFoundHttpException::class,
        \Illuminate\Validation\ValidationException::class,
        \Illuminate\Auth\AuthenticationException::class,
    ],
],

Available log levels:

• debug - Detailed debug information
• info - Interesting events
• notice - Normal but significant events
• warning - Exceptional occurrences that are not errors
• error - Runtime errors
• critical - Critical conditions
• alert - Action must be taken immediately
• emergency - System is unusable

Disable in Specific Environments

Prevent notifications in certain environments (e.g., local development):

'disabledOn' => [
    'local',
    'testing',
],

Cooldown Period

Prevent notification spam for duplicate errors:

'cacheCooldown' => 10, // in minutes

If the same error occurs multiple times within this period, only the first occurrence will trigger a notification.

Storage Path

Customize where error JSON files are stored:

'storage_path' => storage_path('app/errors'),

---

🎯 Features in Detail

Smart Application File Detection

When an error occurs, the package intelligently identifies the first line of code from your application (excluding vendor files) in the stack trace.

Example:

Instead of showing:

File: /vendor/laravel/framework/src/Illuminate/Database/Connection.php
Line: 742

You'll see:

Application File: /app/Http/Controllers/UserController.php  ← Your code!
Application Line: 25                                         ← Your code!
Origin File: /vendor/laravel/framework/src/Illuminate/Database/Connection.php
Origin Line: 742

This makes debugging significantly faster by immediately showing you where in your code the error originated.

Error Details Page

Each error notification includes a unique link to a beautiful, feature-rich error details page:

Features:

• 🌓 Dark/Light Mode - Toggle themes with persistent preference (saved in localStorage)
• 📋 Copy as Markdown - Copy formatted error details for documentation
• 📄 Copy as JSON - Copy raw error data for processing
• 🔗 Share - Use native Web Share API (mobile-friendly)
• 🔒 Secure - Protected by Filament authentication
• 📱 Responsive - Works perfectly on all devices

Information displayed:

• Error message and exception type
• Application file and line (your code)
• Origin file and line (where exception was thrown)
• Full stack trace
• Request details (method, URL, IP, user agent, referrer)
• Authenticated user information (if available)
• Timestamp

Access: Only authenticated Filament users can view error details.

Notification Cooldown

The cooldown system prevents notification spam:

1. When an error occurs, a notification is sent
2. Error details are stored with a timestamp
3. If the same error occurs again within the cooldown period, no new notification is sent
4. After the cooldown expires, the next occurrence will trigger a new notification

Error identification: Errors are identified by a hash of the error message and file path.

---

🚀 Usage

Accessing Error Details

Error detail links are automatically included in:

• Email notifications
• Discord webhook messages

URL format: https://yourapp.com/error-mailer/{errorId}

Example email:

Subject: Error Alert - MyApp

An error has occurred:
Message: Call to undefined method...
File: /app/Http/Controllers/UserController.php
Line: 25

View full details: https://yourapp.com/error-mailer/abc123def456

Scheduled Cleanup

Error JSON files are stored indefinitely by default. To prevent excessive storage usage, schedule a cleanup task in app/Console/Kernel.php:

protected function schedule(Schedule $schedule)
{
    // Delete errors older than 3 months
    $schedule->call(function () {
        $storagePath = config('error-mailer.storage_path');
        $files = File::files($storagePath);

        foreach ($files as $file) {
            if ($file->getMTime() < now()->subMonths(3)->timestamp) {
                File::delete($file->getRealPath());
            }
        }
    })->daily();
}

Recommended retention periods:

• Production: 3-6 months
• Staging: 1-3 months
• Development: 1 month

---

🔧 Advanced Configuration

Complete Configuration Reference

return [
    // Email notification settings
    'email' => [
        'recipient' => ['admin@example.com'],
        'bcc' => [],
        'cc' => [],
        'subject' => 'Error Alert - ' . config('app.name'),
    ],

    // Environments where notifications are disabled
    'disabledOn' => [
        // 'local',
        // 'testing',
    ],

    // Cooldown period in minutes
    'cacheCooldown' => 10,

    // Webhook configuration
    'webhooks' => [
        'discord' => env('ERROR_MAILER_DISCORD_WEBHOOK'),

        'message' => [
            'title' => 'Error Alert - ' . config('app.name'),
            'description' => 'An error has occurred in the application.',
            'error' => 'Error',
            'file' => 'File',
            'line' => 'Line',
            'details_link' => 'View Details',
        ],
    ],

    // Storage path for error JSON files
    'storage_path' => storage_path('app/errors'),

    // Error filtering
    'ignore' => [
        'levels' => [
            // 'debug',
            // 'info',
        ],
        'exceptions' => [
            // \Symfony\Component\HttpKernel\Exception\NotFoundHttpException::class,
        ],
    ],
];

---

📚 Related Projects

This plugin is also available for Laravel projects without Filament:

👉 Laravel Error Mailer

---

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING for details.

Development Setup

# Clone the repository
git clone https://github.com/hugomyb/filament-error-mailer.git
cd filament-error-mailer

# Install dependencies
composer install

# Run tests
composer test

# Run tests with coverage
composer test-coverage

Running Tests

# Run all tests
vendor/bin/pest

# Run specific test file
vendor/bin/pest tests/Unit/ErrorDetailsBuilderTest.php

# Run with coverage
vendor/bin/pest --coverage

---

🔒 Security Vulnerabilities

If you discover a security vulnerability, please send an email to hugomayonobe@gmail.com. All security vulnerabilities will be promptly addressed.

Please review our security policy for more information.

---

👥 Credits

• Hugo Mayonobe - Creator & Maintainer
• All Contributors

---

📄 License

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

---

💡 Support

If you find this package helpful, please consider:

• ⭐ Starring the repository
• 🐛 Reporting bugs or suggesting features via GitHub Issues
• 📖 Improving documentation via pull requests

---

Made with ❤️ for the Filament community