Alert Handlers

An alert handler turns domain events into alerts. Each handler implements App\Contracts\AlertHandlerContract and is registered by a module through the alertHandlers() method of the module contract. When the core receives an event, it iterates over the handlers of the modules enabled for the site and, for each one whose triggerEvents() matches, creates (or resolves) an alert.

Registration

In the module, declare the handlers and the alert types they produce:

public function alertHandlers(): array
{
    return [PanicAlertHandler::class];
}

public function alertTypes(): array
{
    return ['panic'];
}

The AlertHandlerContract interface

All of the methods below are required (the interface defines no defaults).

Identity and module binding

Method	Return	Description
module()	string	Identifier of the module that owns the handler
feature()	?string	Sub-resource the handler depends on, or null if always available. When defined, the central dispatch checks ModuleRegistry::isFeatureEnabledForSite before invoking
type()	string	Alert type (must be listed in the module's alertTypes())
severity()	EventSeverity	Alert severity — a value from the App\Enums\EventSeverity enum

Trigger and resolution

Method	Return	Description
triggerEvents()	list<string>	Event types that create the alert
resolveEvents()	list<string>	Event types that resolve the alert
extractAlertData(DomainEventContract $event)	AlertData	Extracts from the event the data needed to build the alert (App\DataObjects\AlertData object)
matchesForResolve(DomainEventContract $event, Alert $alert)	bool	Decides whether a resolution event matches a specific active alert
autoResolveNote()	string	Note recorded when the alert is auto-resolved by an event
resolveCooldownTtl()	int	Window (in seconds) to prevent immediate reopening after resolution

Deduplication and escalation

Method	Return	Description
dedupTtl()	?int	Deduplication TTL in seconds; null disables dedup
escalatable()	bool	Whether the alert can be escalated
escalationTimeout()	int	Time (seconds) without response before escalation

Presentation

Method	Return	Description
title(Alert $alert)	string	Title displayed for the alert
description(Alert $alert)	string	Description/detail of the alert

Alert lifecycle

1. A domain event (DomainEventContract) is emitted.
2. The core selects the handlers of the modules enabled for the site; if the handler declares a feature(), the sub-resource must also be active.
3. If the event type is in triggerEvents(), the handler uses extractAlertData() to create the alert — respecting dedupTtl() to avoid duplication.
4. title() and description() define how the alert appears; severity() classifies the urgency.
5. When an event from resolveEvents() arrives, matchesForResolve() decides which active alert it resolves; autoResolveNote() documents the resolution and resolveCooldownTtl() prevents immediate reopening.
6. If escalatable() and the alert goes without response for escalationTimeout() seconds, the escalation flow is triggered.

Next steps

• Module Contract — How alertHandlers() and features() fit together
• About Alerts — How alerts appear to the operator
• Report Handlers — The sibling contract for reports