Critical Alerting Bundle Laravel Package

Getting Started

3.1.0 is an additive release: nothing you already have breaks at the public API level, and the main new capability is that exception notifications can now carry the request's Referer header. Start by confirming you're on the new version and that your listener is wired up:

composer require <vendor>/<package>:^3.1

First place to look is ExceptionListener — it now receives a RequestContext dependency and hands it to the notification it builds. In a standard Laravel app you don't need to touch this: the container resolves RequestContext for you. Verify your notification channel config (bot token / chat id for TelegramNotification) is still published and intact, then trigger a test exception from a browser request with a Referer header set and confirm it appears in the Telegram message.

Your first real use case: reproducing a production bug. Open the Telegram alert, read the Referer, and you immediately know which page the user was on when the exception fired — previously you'd be guessing from the URL in the stack trace alone.

Implementation Patterns

Let the listener do the work. The default path is unchanged: register ExceptionListener on your exception handler (or let the package auto-register it), and every reported exception produces a notification enriched with referer data when a request context is available. This is the pattern for 90% of apps.

Extend AbstractNotification and use the new referer field. If you have a custom notification class, you now inherit a referer property with getter/setter. Populate it in your formatter:

class SlackNotification extends AbstractNotification
{
    public function __toString(): string
    {
        return sprintf(
            "%s\n%s\nReferer: %s",
            $this->getTitle(),
            $this->getMessage(),
            $this->getReferer() ?? 'n/a'
        );
    }
}

Build notifications manually with createFromThrowable() and a RequestContext. This is the integration point for jobs, console commands, or custom handlers where you want referer context but aren't going through the listener:

$context = RequestContext::fromRequest(request()); // or however the package exposes construction
$notification = TelegramNotification::createFromThrowable($e, $context);

The second argument is optional, so existing calls to createFromThrowable($e) keep working — referer is simply absent.

Workflow tip: route by referer. Because referer is now a first-class field on the notification, you can branch on it — send checkout-page exceptions to one chat and admin-panel exceptions to another, or attach the referer as a tag in your alerting backend.

Gotchas and Tips

ExceptionListener's constructor changed. It now takes RequestContext as a dependency. Container-resolved usage is fine, but if you instantiate the listener manually (tests, custom wiring, service providers) you must pass the context — otherwise you'll get an argument-count error. This is the one place 3.1.0 can bite you.

Referer is frequently absent. Direct navigations, bookmarks, Referer-Policy: no-referrer responses, CLI/cron/queue contexts, and API clients will all yield null. Always null-check getReferer() before interpolating it; TelegramNotification handles this internally, but your custom notifications must too.

Treat referer as untrusted input. It's a client-supplied header. Don't render it into HTML without escaping, don't use it for authorization decisions, and be aware it can carry query strings with tokens or PII — consider stripping the query string before it lands in a chat log that many people can read.

Long or spoofed values. Referers can be arbitrarily long; some Telegram/chat backends truncate or reject oversized messages. If you extend the message format, truncate the referer yourself (e.g. Str::limit($referer, 200)).

Queued notifications and context capture. If notifications are queued, the RequestContext is read at notification-creation time in the listener, which is correct — but if you defer creation into a job, capture the referer before dispatching, because request() won't exist when the job runs.

Testing. In feature tests, set the header explicitly ($this->withHeader('Referer', 'https://app.test/checkout')) and assert on the notification's getReferer(). For unit tests of custom notifications, set the referer via the setter rather than constructing a full RequestContext.

Extension point to watch. RequestContext is the natural seam for adding more request-derived data (user agent, request ID, route name) in future releases. If you need extra context today, wrap or decorate it and pass your enriched notification into the listener rather than forking the package.