Notify Exceptions Laravel Package

Getting Started

thedragoncode/notify-exceptions hooks into Laravel’s exception reporting pipeline and sends exception details through Laravel’s notification system, so day-to-day use is mostly configuration rather than code. v4.1.0 is a minor release in the 4.x line; the published notes are only a GitHub compare link, so treat it as a backwards-compatible patch/minor unless the diff shows otherwise.

Minimal setup:

composer require thedragoncode/notify-exceptions:^4.1
php artisan vendor:publish --tag=notify-exceptions-config

Then open config/notify-exceptions.php. That file is the first place to look: it controls whether notifications are enabled, which channels are used, recipient addresses/chat IDs, throttling, and which notification class is dispatched.

At minimum, configure one channel through environment variables, for example mail:

NOTIFY_EXCEPTIONS_ENABLED=true
[email protected]

A good first use case is production or staging alerting: route unhandled exceptions to a team Telegram chat or an on-call mailbox so 500s are visible without waiting for someone to inspect logs. Smoke-test it with Laravel’s reporter rather than by deliberately breaking a route:

php artisan tinker
>>> report(new RuntimeException('notify-exceptions smoke test'));

If the notification arrives, the package is wired correctly. After changing environment variables, run php artisan config:clear before testing again.

Implementation Patterns

Environment-gated alerting. Keep the package disabled locally and enable it only where a human should be paged:

NOTIFY_EXCEPTIONS_ENABLED=false
# production/staging
NOTIFY_EXCEPTIONS_ENABLED=true

This prevents local stack traces from spamming shared channels and keeps test runs quiet.

Channel routing by severity or team. Use mail for on-call escalation and a chat channel for ambient awareness. Configure different chat IDs or recipient lists per environment so staging errors never land in the production incident channel. The package uses Laravel notifications, so any channel supported by your installed notification drivers can be plugged in.

Customize the notification, not the package. Publish or extend the package’s exception notification class and point the config at your subclass. This is the cleanest place to add environment names, app versions, request URLs, user IDs, or links to your log viewer:

namespace App\Notifications;

use TheDragonCode\NotifyExceptions\Notifications\ExceptionNotification as BaseNotification;

class ExceptionNotification extends BaseNotification
{
    // Override toMail()/toTelegram()/etc., enrich the payload, then call parent.
}

Check the published config for the exact notification-class key and base class path in your installed version.

Filter noise through Laravel’s exception configuration. The package only sees exceptions Laravel reports. In Laravel 11+ bootstrap/app.php, use withExceptions() to exclude validation failures, 404s, auth exceptions, and other expected control flow:

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->dontReport([
        \Illuminate\Auth\AuthenticationException::class,
        \Illuminate\Validation\ValidationException::class,
        \Symfony\Component\HttpKernel\Exception\NotFoundHttpException::class,
    ]);
})

This is usually better than maintaining a separate ignore list inside the package config because it also affects other reporters.

Throttle and deduplicate. A failing queue worker or a dead database can generate thousands of identical exceptions per minute. Enable the package’s throttling settings and consider grouping by exception class plus normalized message. If you need finer control, wrap custom reporting logic with RateLimiter or a short-lived cache key per exception fingerprint.

Queue the notification. A synchronous mail or HTTP notification inside the exception handler slows down error responses and can time out. If you extend the notification class, implement ShouldQueue and ensure a worker is running. For chat channels, expect provider rate limits; queueing plus throttling is the practical combination.

Use report() deliberately. Caught exceptions are not reported automatically. If a try/catch block handles an exception but you still want an alert, call report($e) explicitly. Conversely, do not call report() for expected business-rule exceptions unless you genuinely want a notification.

Test the reporting path without triggering real alerts. In tests, either disable the package through config or fake the notification:

Notification::fake();

report(new RuntimeException('test'));

Notification::assertSentOnDemand(ExceptionNotification::class);

This gives you regression coverage for your custom notification payload without hitting external channels.

Gotchas and Tips

The v4.1.0 changelog is link-only. The release notes contain no enumerated changes, so review the GitHub compare diff or the repository changelog before upgrading. Semver suggests no breaking changes, but verify the PHP and Laravel support matrix if you are on the edges of the supported versions.

Config caching bites. The package reads its settings from config. After changing .env values, run php artisan config:clear (and config:cache again in production). A stale config cache is the most common reason “the notification isn’t being sent.”

Only reported exceptions are notified. Exceptions swallowed in try/catch, handled by custom middleware, or converted to responses before reaching Laravel’s handler will not trigger the package. If an alert is missing, first confirm the exception reaches report().

HTTP exception noise. 404s, 419s, 401s, and validation errors can drown out real failures. Disable HTTP-exception notifications if the package exposes that toggle, or exclude those classes via dontReport(). Review the channel after a deploy to confirm you are not paging on routine traffic.

Notification recursion and cascading failures. If the notification transport itself fails—bad Telegram token, SMTP outage—the resulting exception may also be reported. Combine throttling with a circuit-breaker approach or disable the package’s own reporting during transport failures. Otherwise a broken mail server can generate a second storm of alerts.

Sensitive data leakage. Exception messages and stack traces can contain request payloads, SQL, tokens, or environment details. Scrub the payload in your custom notification class before sending to chat channels, and restrict the mail recipient list. Treat alert channels as production data sinks.

Provider rate limits. Telegram, Slack, and mail providers enforce quotas. A burst of exceptions can result in HTTP 429 responses and dropped alerts. Throttle at the application level rather than relying on the provider to absorb the burst.

Queue worker dependency. If your custom notification implements ShouldQueue, alerts stop silently when the queue is down—precisely when you may need them most. Monitor the queue worker separately, or keep a minimal synchronous fallback for critical exceptions.

Namespace and major-version changes. The package moved under the TheDragonCode namespace in recent majors. If you are upgrading from an older 3.x install, update imports, config references, and any subclasses of the notification class. Do not assume class paths from older blog posts are still valid.

Local debugging. Temporarily enable the package locally with a personal chat ID or a Mailtrap-style mailbox. Use report() from Tinker or a test rather than throwing from a browser route, so you can iterate quickly without confusing your application flow.

Extension points. Prefer the published config’s notification-class and notifiable hooks over modifying vendor code. If you need per-exception routing, wrap the reporting call in your own service and decide whether to call report() or dispatch a custom notification directly.