artryazanov/laravel-error-mailer
| Install | |
|---|---|
composer require artryazanov/laravel-error-mailer |
|
| Latest Version: | v1.2.0 |
| PHP: | ^8.2 |
| Laravel: | 12 · 13 |
| Older releases: | 11 |
| License: | MIT |
| Last Updated: | Nov 2, 2026 |
| Links: | GitHub · Packagist |
📧 Laravel Error Mailer
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
$_SERVERarray. - Console Commands (CLI): Command arguments and
$_SERVERarray.
- Web Requests: URL, Method, User info, Request Body (including safe metadata for uploaded files), Headers, Cookies, and
- 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.
Related Packages
Powerful PHP database abstraction layer (DBAL) with many features for database s...
Laravel Serializable Closure provides an easy and secure way to serialize closur...
Cli error handling for console/command-line PHP applications.
Version History
| Version | Released | PHP | Laravel | License |
|---|---|---|---|---|
| v1.2.0 | ^8.2 | ^12.0| | MIT | |
| v1.1.1 | ^8.2 | ^11.0| | MIT | |
| v1.1.0 | ^8.2 | ^11.0| | MIT | |
| v1.0.7 | ^8.2 | ^11.0| | MIT | |
| v1.0.6 | ^8.2 | ^11.0| | MIT | |
| v1.0.5 | ^8.2 | ^11.0| | MIT | |
| v1.0.4 | ^8.2 | ^11.0| | MIT | |
| v1.0.3 | ^8.2 | ^11.0| | MIT | |
| v1.0.2 | ^8.2 | ^11.0| | MIT | |
| v1.0.1 | ^8.2 | ^11.0| | MIT | |
| v1.0.0 | ^8.2 | ^11.0| | MIT |