README

Centralised alert proxy for TYPO3 extensions — sends Pushover push notifications with built-in rate limiting and deduplication. Other extensions simply call AlertManager::notify() and AlertManager::resolve(); ot_alerts handles throttling, state tracking, and channel dispatch.

Features

• Pushover push notifications via REST API with HTML formatting
• Event key and occurrence count visible in every notification
• Optional tappable link button in Pushover (via context['url'])
• Rate limiting: first occurrence triggers immediately, then once per configurable reminder interval
• State machine: NEW → NOTIFIED → RESOLVED — resolved errors trigger fresh notifications when they reappear
• DB-backed event log (tx_otalerts_events) for audit trail and future backend module
• Optional integration: inject ?AlertManager via constructor — ot_alerts is not a hard dependency, the service is simply null when not installed
• Configurable reminder interval via TYPO3 Extension Configuration

Requirements

Installation

composer require oliverthiele/ot-alerts

After installation, run database schema update:

vendor/bin/typo3 database:updateschema

Configuration

Environment Variables

Add the following to your .env file:

PUSHOVER_APP_TOKEN=your_app_token_here
PUSHOVER_USER_KEY=your_user_key_here

Both values are available in your Pushover dashboard.

Extension Configuration

Configure in the TYPO3 backend under Admin Tools → Settings → Extension Configuration → ot_alerts:

Usage

Optional dependency via constructor injection

The recommended integration pattern uses TYPO3's Symfony DI container. Declare ?AlertManager as a nullable constructor parameter — when ot_alerts is not installed, the container injects null and all calls are silently skipped via the null-safe operator:

use OliverThiele\OtAlerts\Alert\Alert;
use OliverThiele\OtAlerts\Alert\AlertSeverity;
use OliverThiele\OtAlerts\Service\AlertManager;

class MyService
{
    public function __construct(
        private readonly ?AlertManager $alertManager = null,
    ) {}

    public function doSomething(): void
    {
        // ... your logic ...

        // notify — only fires when ot_alerts is installed
        $this->alertManager?->notify(new Alert(
            source: 'my_extension',
            eventKey: 'api.connection.failed',
            message: 'Could not connect to external API',
            severity: AlertSeverity::ERROR,
        ));
    }
}

No class_exists() guard or GeneralUtility::makeInstance() needed — the container resolves the optional service automatically.

Sending an alert

$this->alertManager?->notify(new Alert(
    source: 'my_extension',
    eventKey: 'api.connection.failed',
    message: 'Could not connect to external API',
    severity: AlertSeverity::ERROR,
));

Sending an alert with a URL

Pass context['url'] to add a tappable link button to the Pushover notification. This is useful to open the affected page directly from the push:

$this->alertManager?->notify(new Alert(
    source: 'my_extension',
    eventKey: 'api.connection.failed',
    message: 'Could not connect to external API',
    severity: AlertSeverity::ERROR,
    context: ['url' => 'https://example.com/affected-page/'],
));

Resolving an alert

Call resolve() once the error condition is no longer present. This resets the state so the next occurrence will trigger a fresh notification immediately.

$this->alertManager?->resolve('my_extension', 'api.connection.failed');

Notification format

Pushover messages use HTML formatting for readability:

Title:    [ERROR] my_extension

Message:  api.connection.failed       ← bold event key

          Could not connect to
          external API

          occurrence #3               ← italic, only shown from 2nd occurrence onwards

[Open page →]                         ← tappable link button, only shown when context['url'] is set

Severity levels and Pushover priorities

Emergency notifications (CRITICAL) require acknowledgement in the Pushover app.

Notification behaviour

First error  →  Push sent immediately  →  status: NOTIFIED
Still broken →  Push after reminderInterval  →  status: NOTIFIED
Error fixed  →  resolve() called  →  status: RESOLVED
New error    →  Push sent immediately  →  status: NOTIFIED

CLI

Test notification

Verify that Pushover credentials are configured and a push is delivered:

vendor/bin/typo3 ot_alerts:test

Send with a specific severity:

vendor/bin/typo3 ot_alerts:test --severity=error

Reset the rate limit after the test so the next real error triggers immediately:

vendor/bin/typo3 ot_alerts:test --resolve

Show per-channel dispatch result including HTTP status:

vendor/bin/typo3 ot_alerts:test -v

Show the raw Pushover API response body (full debug output):

vendor/bin/typo3 ot_alerts:test -vvv

If the alert was previously sent and the reminder interval has not yet elapsed, the command shows [WARNING] Rate limit active. Use --resolve to bypass: the command pre-resolves the event before sending (so the rate limit is skipped) and post-resolves after (so the next test also sends immediately).

The command shows which ENV variables are present, dispatches the alert, and prints the result.

License

GPL-2.0-or-later — © 2025 Oliver Thiele