Error Mailer

• ✨ Key Features
• 📋 Table of Contents
• 📦 Installation
  • Step 1: Install via Composer
  • Step 2: Publish Configuration
  • Step 3: Configure Mail Server
  • Step 4: Register the Plugin
  • Step 5: (Optional) Publish Views
• ⚙️ Configuration
  • Email Configuration
  • Discord Webhook
  • Error Filtering
  • Disable in Specific Environments
  • Cooldown Period
  • Storage Path
• 🎯 Features in Detail
  • Smart Application File Detection
  • Error Details Page
  • Notification Cooldown
• 🚀 Usage
  • Accessing Error Details
  • Scheduled Cleanup
• 🔧 Advanced Configuration
  • Complete Configuration Reference
• 📚 Related Projects
• 🤝 Contributing
  • Development Setup
  • Running Tests
• 🔒 Security Vulnerabilities
• 👥 Credits
• 📄 License
• 💡 Support

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