README

A powerful Laravel package that automatically catches exceptions and sends beautifully formatted, responsive email notifications to multiple recipients.

🚀 Features

🚨 Automatic Exception Catching - Seamlessly integrates with Laravel's exception handler
📧 Multiple Recipients - Send alerts to multiple email addresses
📱 Responsive Email Design - Beautiful emails that work on all devices and email clients
⚡ Rate Limiting - Prevents email spam with intelligent throttling (enabled by default)
🔧 Configurable Filtering - Choose which exception types to report/skip
📊 Rich Information - Includes request data, stack trace, user info, and environment details
⚙️ Queue Support - Async email sending for better performance
🧪 Built-in Testing - Command line and web testing tools included
🎨 Stack Trace Enhancement - Color-coded, row-by-row stack traces with source type indicators

📦 Installation

composer require najibismail/laravel-exception-catcher

The service provider will be automatically registered (Laravel 5.5+).

⚡ Quick Start

Publish configuration:

php artisan vendor:publish --provider="NajibIsmail\LaravelExceptionCatcher\ExceptionCatcherServiceProvider" --tag="config"

Configure emails in .env:

EXCEPTION_CATCHER_TO_EMAIL="admin@yourapp.com"
EXCEPTION_CATCHER_FROM_EMAIL="noreply@yourapp.com"

Add to your Exception Handler (app/Exceptions/Handler.php):

use NajibIsmail\LaravelExceptionCatcher\Traits\SendsExceptionEmails;

class Handler extends ExceptionHandler
{
    use SendsExceptionEmails;
    
    // The trait automatically handles exception reporting
    // No need to override the report() method
}

Test it:
```
php artisan exception:test
```

⚙️ Configuration

Edit config/exception-catcher.php to customize behavior:

return [
    'enabled' => env('EXCEPTION_CATCHER_ENABLED', true),
    
    'emails' => [
        'to' => explode(',', env('EXCEPTION_CATCHER_TO_EMAIL', 'admin@example.com')),
        'from' => env('EXCEPTION_CATCHER_FROM_EMAIL', 'noreply@example.com'),
        'from_name' => env('EXCEPTION_CATCHER_FROM_NAME', 'Exception Catcher'),
    ],
    
    'queue_enabled' => env('EXCEPTION_CATCHER_QUEUE_ENABLED', false),
    'include_stack_trace' => env('EXCEPTION_CATCHER_INCLUDE_STACK_TRACE', true),
    
    'rate_limiting' => [
        'enabled' => env('EXCEPTION_CATCHER_RATE_LIMITING_ENABLED', true),
        'max_emails_per_hour' => env('EXCEPTION_CATCHER_MAX_EMAILS_PER_HOUR', 10),
        'cache_key_prefix' => 'exception_catcher_',
    ],
    
    'skip_exceptions' => [
        Symfony\Component\HttpKernel\Exception\NotFoundHttpException::class,
        'Illuminate\Auth\AuthenticationException',
        'Illuminate\Validation\ValidationException',
        'Symfony\Component\HttpKernel\Exception\HttpException',
    ],
    
    'include_request_data' => env('EXCEPTION_CATCHER_INCLUDE_REQUEST', true),
];

Environment Variables

Add these to your .env file:

# Exception Catcher Configuration
EXCEPTION_CATCHER_ENABLED=true
EXCEPTION_CATCHER_TO_EMAIL="admin@yourapp.com,dev@yourapp.com"
EXCEPTION_CATCHER_FROM_EMAIL="noreply@yourapp.com"
EXCEPTION_CATCHER_FROM_NAME="Your App Name"
EXCEPTION_CATCHER_QUEUE_ENABLED=false
EXCEPTION_CATCHER_INCLUDE_STACK_TRACE=true
EXCEPTION_CATCHER_INCLUDE_REQUEST=true

# Rate Limiting Configuration
EXCEPTION_CATCHER_RATE_LIMITING_ENABLED=true
EXCEPTION_CATCHER_MAX_EMAILS_PER_HOUR=10

# Laravel Mail Configuration  
MAIL_MAILER=smtp
MAIL_HOST=your-smtp-host
MAIL_PORT=587
MAIL_USERNAME=your-email
MAIL_PASSWORD=your-password
MAIL_ENCRYPTION=tls

🔧 Integration Methods

Method 1: Using the Trait (Recommended)

The trait automatically handles exception reporting. Simply add it to your Exception Handler:

<?php

namespace App\Exceptions;

use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;
use NajibIsmail\LaravelExceptionCatcher\Traits\SendsExceptionEmails;
use Throwable;

class Handler extends ExceptionHandler
{
    use SendsExceptionEmails;
    
    // The trait automatically overrides the report() method
    // No additional code needed
}

Method 2: Manual Integration

If you prefer manual control, you can manually call the exception emailer:

<?php

namespace App\Exceptions;

use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;
use Throwable;

class Handler extends ExceptionHandler
{
    public function report(Throwable $exception)
    {
        parent::report($exception);

        // Send exception email
        if (app()->bound('exception.emailer')) {
            app('exception.emailer')->handle($exception, request());
        }
    }
}

Method 3: Using the Facade

You can also send exception emails manually anywhere in your code:

use NajibIsmail\LaravelExceptionCatcher\Facades\ExceptionCatcher;

try {
    // Your code here
} catch (Exception $e) {
    ExceptionCatcher::handle($e, request());
    throw $e; // Re-throw if needed
}

🧪 Testing

Command Line Testing

php artisan exception:test [type]

Available Types: runtime, invalid, custom, db, fatal, validation, http

Web Route Testing

GET http://your-app.com/exception-test
GET http://your-app.com/exception-test/runtime

Results: Exception caught → Email sent → Beautiful responsive template

📧 Email Features

Responsive Design - Adapts to desktop, tablet, and mobile
Email Client Support - Gmail, Outlook, Apple Mail, Thunderbird
Enhanced Stack Traces - Color-coded with source indicators (ORIGIN, APP, VENDOR)
Rich Information - Request data, user details, environment info
Automatic From Address - Uses configuration or Laravel's default mail settings
Queue Support - Optional async email sending for better performance

🔍 Troubleshooting

Not Receiving Emails?

Check your Laravel mail configuration
Verify recipient email addresses in config
Check spam/junk folders

Test Laravel mail with php artisan tinker:

Mail::raw('Test', function($msg) {
    $msg->to('your-email@example.com')->subject('Test');
});

Command Not Found?

Run composer dump-autoload
Verify package installation: composer show najibismail/laravel-exception-catcher

Web Routes Not Working?

Clear route cache: php artisan route:clear
Check if service provider is registered: php artisan route:list | grep exception-test

Rate Limiting Issues?

Check cache configuration in config/cache.php
Clear cache: php artisan cache:clear

Adjust rate limits in your .env file:

EXCEPTION_CATCHER_RATE_LIMITING_ENABLED=true
EXCEPTION_CATCHER_MAX_EMAILS_PER_HOUR=20  # Increase if needed

Or disable rate limiting temporarily:

EXCEPTION_CATCHER_RATE_LIMITING_ENABLED=false

🏗️ Package Structure

packages/laravel-exception-catcher/
├── .gitignore                          # Git ignore rules
├── LICENSE                             # MIT License  
├── README.md                           # This documentation
├── composer.json                       # Package configuration
├── config/
│   └── exception-catcher.php          # Configuration file
├── resources/
│   └── views/
│       └── exception-email.blade.php  # Responsive email template
├── routes/
│   └── web.php                        # Test routes
└── src/
    ├── Console/Commands/
    │   └── TestExceptionCatcher.php    # Test command
    ├── ExceptionCatcherServiceProvider.php # Service provider
    ├── ExceptionEmailer.php            # Core logic
    ├── Facades/
    │   └── ExceptionCatcher.php        # Facade
    ├── Mail/
    │   └── ExceptionNotification.php   # Mailable class
    └── Traits/
        └── SendsExceptionEmails.php    # Handler trait

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

� Support

Issues: GitHub Issues
Email: najibismail1986@gmail.com
Discussions: GitHub Discussions

�📄 License

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

🏷️ Version

Current Version: 1.0.7
Laravel Compatibility: 8.x, 9.x, 10.x, 11.x
PHP Compatibility: 8.0+

Made with ❤️ for the Laravel community

najibismail / laravel-exception-catcher

Maintainers

Details