Exception Handler Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package. As a Laravel developer, treat it as either:

1. A component you may encounter while maintaining a Symfony service, or
2. A reference implementation for “mail the exact exception context” behavior you can reproduce in Laravel’s app/Exceptions/Handler.php.

Minimal Symfony setup if you are actually in a Symfony app:

composer require kick-in/exception-handler-bundle

Then:

1. Register the bundle in config/bundles.php:

   KickIn\ExceptionHandlerBundle\ExceptionHandlerBundle::class => ['all' => true],
   

2. Read the bundle’s README and DependencyInjection/Configuration.php first. That is the source of truth for config keys, mailer requirements, and recipient settings.
3. Configure a working mail transport. The bundle’s core value is sending the exact exception, so a broken mailer makes it useless.
4. Trigger a controlled exception in a non-production environment and verify the mail body contains the exception class, message, stack trace, and request context.

First realistic use case: replace generic “something went wrong” alerts with an email containing the exact exception and enough context to reproduce it. In Laravel terms, this is similar to customizing report() in app/Exceptions/Handler.php and sending a Mailable, but the Symfony bundle handles the wiring for you.

Where to look first:

• README.md for install and config.
• Bundle extension / configuration class for available options.
• Exception listener/subscriber class to understand what gets caught.
• Mail templates to see what context is included.
• Composer constraints to confirm Symfony and mailer compatibility.

Implementation Patterns

1. Production-only exception mailing

The most sensible pattern is environment gating:

• Local/dev: log only, no mail.
• Staging: mail to a team inbox.
• Production: mail only critical exceptions, or route through your existing monitoring stack.

In Symfony, this means keeping the bundle enabled but configuring recipients and mail behavior per environment. In Laravel, the equivalent is:

// app/Exceptions/Handler.php
public function report(Throwable $e): void
{
    if (app()->environment('production') && $this->shouldMail($e)) {
        Mail::to(config('services.alerts.email'))
            ->queue(new ExceptionOccurred($e, request()));
    }

    parent::report($e);
}

2. Throttle and deduplicate before mailing

Do not mail every exception. A single broken request path can generate thousands of mails. Patterns:

• Mail only once per exception class + normalized message per time window.
• Use cache locks or rate limiters.
• Prefer queued mail over synchronous send().
• Suppress mail for validation, authentication, 404, and other expected exceptions.

Laravel equivalent:

RateLimiter::attempt(
    'exception-mail:'.md5($e::class.$e->getMessage()),
    1,
    fn () => Mail::to($to)->queue(new ExceptionOccurred($e)),
    300
);

3. Decorate or wrap the handler instead of modifying vendor code

If the bundle’s handler is a service, decorate it or add an event listener rather than editing vendor files. This keeps upgrades possible.

In Laravel, the same principle applies: put custom reporting in report() or a dedicated reporter service, not inside framework internals.

4. Pair with structured logging and monitoring

Email is a notification channel, not an observability system. Use it alongside:

• Laravel: Log::critical(), Sentry, Flare, Bugsnag, etc.
• Symfony: Monolog, Sentry, etc.

Recommended flow:

1. Exception occurs.
2. Structured log entry is written with exception class, message, request ID, user ID, and stack trace.
3. Monitoring tool receives the event.
4. Email is sent only for high-signal cases or as a fallback.

5. Use custom exception types to control routing

Create domain-specific exceptions such as PaymentFailedException or SyncJobFailedException. Then decide which ones should trigger mail. This avoids brittle message-string matching.

6. Integrate with queue workers and console commands

HTTP exceptions are not the only source. If you use the same pattern in Laravel queue jobs or Symfony console commands, make sure the mailer context still captures:

• Job/command name.
• Payload identifiers, but not secrets.
• Attempt number.
• Environment and release version.

7. Test with a local mail catcher

Use Mailpit, MailHog, or Symfony Mailer’s log transport during development. Assert that:

• The mail is sent for the intended exception.
• The mail is not sent for ignored exceptions.
• The body contains the exception class and stack trace.
• No passwords, tokens, or personal data leak into the mail.

Gotchas and Tips

It is not a Laravel package

Do not run composer require kick-in/exception-handler-bundle in a Laravel app expecting package discovery, a service provider, or a config/exception-handler.php file. It will not integrate with Laravel’s exception handler. Port the idea, not the dependency.

Very low adoption

With 1 star and 0 dependents, expect limited community documentation, few Stack Overflow answers, and possible edge-case bugs. Read the source before relying on it in production. Pin the version in composer.json.

Mail storms and recursion

A failure inside the mailer can trigger another exception, which can trigger another mail attempt. Guard against this:

• Wrap mail sending in its own try/catch.
• Never let notification failure replace the original exception.
• Add rate limiting and deduplication.
• Disable mail for exceptions thrown by the mailer itself.

Fatal errors and memory exhaustion may not be mailed

PHP fatal errors, OOM kills, and process crashes can bypass normal exception handling. Email alerting alone is not enough. Use shutdown handlers, server-level monitoring, and log aggregation.

Configuration cache quirks in Symfony

After changing bundle config, clear the cache:

php bin/console cache:clear

In production, ensure config is rebuilt during deploy. A stale config cache can make it look like the bundle is ignoring your recipients or transport settings.

Mailer compatibility

Confirm whether the bundle expects Symfony Mailer, SwiftMailer, or a generic mailer service. Older Symfony bundles may assume deprecated APIs. Check composer.json constraints against your Symfony version.

Synchronous mail can slow requests

If the bundle sends mail inline, an SMTP timeout can turn a 500 into a very slow 500. Prefer async transports or queued messages where possible.

Privacy and secrets in stack traces

Exception mails often include request parameters, headers, SQL, and environment details. Redact authorization headers, cookies, passwords, API tokens, and personal data before sending.

Debugging checklist

If mail is not arriving:

1. Confirm the bundle is registered.
2. Confirm the exception type is actually handled by the bundle’s listener.
3. Check var/log for mailer transport errors.
4. Verify the transport DSN and recipient config.
5. Trigger a known exception in a safe environment.
6. Temporarily switch to a local mail catcher or log transport.
7. Clear Symfony cache after config changes.

Extension points to inspect

Look for:

• The exception listener/subscriber class.
• The handler service definition.
• Mail templates.
• Configuration tree and default values.
• Events dispatched before or after handling.

These are the safest places to customize without forking the bundle.

Recommended Laravel-side equivalent

If your goal is simply “email me the exact exception,” do not introduce a Symfony bundle into Laravel. Use Laravel’s native facilities:

• app/Exceptions/Handler.php for reporting.
• Mail::to(...)->queue(...) for delivery.
• RateLimiter for throttling.
• Log and a monitoring package for observability.
• A dedicated ExceptionOccurred mailable with redacted context.

That gives you the same outcome with first-class Laravel support and no cross-framework coupling.