Eigene Admin-Benachrichtigungen im Magento-Backend registrieren

1. Wie das eingebaute Notification-System funktioniert

Das Modul Magento_AdminNotification stellt die Glocke oben rechts im Backend bereit, die jeder Magento-Administrator kennt. Hinter dieser Glocke steckt die Tabelle adminnotification_inbox, verwaltet über Magento\AdminNotification\Model\Inbox und den zugehörigen Resource-Model. Jede Zeile in dieser Tabelle ist eine Admin-Benachrichtigung mit Titel, Beschreibung, optionalem Link, Schweregrad und einem is_read-Flag. Der ungelesene Zähler an der Glocke ist eine einfache Aggregation über is_read = 0, die bei jedem Seitenaufruf im Backend neu berechnet wird.

Magento nutzt dieses System selbst intensiv: Sicherheitswarnungen zu veralteten Composer-Paketen, Hinweise auf verfügbare Patches und Meldungen des offiziellen Magento-Security-Feeds landen als Backend-Benachrichtigungen in genau dieser Inbox. Der Cron-Job update_notifications aus Magento_AdminNotification ruft dafür in regelmäßigen Abständen einen externen Feed ab und schreibt neue Einträge über InboxFactory in die Tabelle. Für eigene Module ist genau dieser Mechanismus interessant: Statt eines externen Feeds prüft ein eigener Cron-Job eine projektspezifische Bedingung, zum Beispiel den Ablauf eines SSL-Zertifikats oder den Status einer nächtlichen API-Synchronisation, und schreibt bei Bedarf eine neue Zeile in dieselbe Inbox-Tabelle.

Der zweite Baustein des Notification-Systems ist unabhängig von der Inbox: die System Messages. Sie erscheinen als rotes oder gelbes Banner direkt unter der Admin-Navigation und werden über Magento\Framework\Notification\MessageInterface-Implementierungen bereitgestellt, die in einer virtuellen Liste (Magento\Framework\Notification\MessageList) registriert sind. Beide Mechanismen, Inbox und System Message, existieren parallel und unabhängig voneinander, lassen sich aber in einem Modul kombiniert einsetzen, um sowohl eine dauerhafte, historisierte Meldung als auch eine dringende, sofort sichtbare Warnung auszugeben.

2. Schweregrade und die Inbox-Datenstruktur

Jede Inbox-Benachrichtigung besitzt einen Schweregrad, definiert über drei Konstanten in Magento\AdminNotification\Model\Inbox: NOTICE_SEVERITY_MINOR (Wert 1), NOTICE_SEVERITY_MAJOR (Wert 2) und NOTICE_SEVERITY_CRITICAL (Wert 3). Der Schweregrad steuert nicht nur die Farbe des Icons in der Notification-Liste, sondern auch, welcher Eintrag beim Öffnen der Glocke priorisiert oben erscheint. Eine MINOR-Meldung eignet sich für informative Hinweise wie abgeschlossene Wartungsarbeiten, MAJOR für Warnungen wie einen bald ablaufenden API-Schlüssel und CRITICAL für Zustände, die sofortiges Handeln erfordern, etwa einen fehlgeschlagenen Zahlungsanbieter-Sync.

Die Spalten der adminnotification_inbox-Tabelle sind bewusst generisch gehalten: severity, date_added, title, description, url, is_read, is_remove und notification_type. Für die meisten eigenen Admin-Benachrichtigungen reicht diese Struktur vollständig aus, ohne dass eine eigene Tabelle über db_schema.xml notwendig wird. Erst wenn projektspezifische Metadaten dauerhaft mit der Benachrichtigung verknüpft werden müssen, etwa eine Referenz auf eine bestimmte Bestellung oder einen Lieferanten-Datensatz, lohnt sich eine eigene Erweiterungstabelle mit einer Fremdschlüsselbeziehung auf adminnotification_inbox.notification_id. In diesem Fall definiert man in der eigenen db_schema.xml eine neue Tabelle und referenziert die Inbox-ID als Fremdschlüssel, statt die Kerntabelle von Magento zu verändern.

Das Feld is_remove unterscheidet zwischen dismissible und persistenten Benachrichtigungen. Steht is_remove auf 1, kann der Administrator die Meldung über das X-Symbol dauerhaft entfernen. Steht es auf 0, bleibt die Backend-Benachrichtigung in der Inbox stehen, bis sie explizit über den Controller Magento\AdminNotification\Controller\Adminhtml\Notification\MarkAsRead als gelesen markiert wird. Für kritische Compliance-Hinweise, die nicht versehentlich weggeklickt werden sollen, ist is_remove = 0 die richtige Wahl, während informative Hinweise typischerweise dismissible sind.

3. Eigenes Repository für Inbox-Benachrichtigungen

Statt die Inbox über den generischen InboxFactory direkt in Business-Logik-Klassen zu befüllen, empfiehlt sich ein eigenes Repository nach dem Service-Contract-Muster. Das kapselt die Erzeugungslogik, macht sie testbar und erlaubt es, projektspezifische Regeln zu ergänzen, etwa das Verhindern von Duplikaten innerhalb eines Zeitfensters. Das folgende Beispiel zeigt ein Repository, das eine Admin-Benachrichtigung für eine bevorstehende Zertifikatsablauf-Warnung erzeugt und dabei Constructor Property Promotion nach PHP-8.4-Konventionen nutzt.

<?php

declare(strict_types=1);

namespace Mironsoft\NotificationHub\Model;

use Magento\AdminNotification\Model\InboxFactory;
use Magento\AdminNotification\Model\Inbox;
use Mironsoft\NotificationHub\Api\CertificateNotifierInterface;

/**
 * Writes certificate expiry warnings into the Magento_AdminNotification inbox.
 */
class CertificateNotifier implements CertificateNotifierInterface
{
    /**
     * @param InboxFactory $inboxFactory Factory for the Inbox model used to persist notifications.
     */
    public function __construct(
        private readonly InboxFactory $inboxFactory
    ) {
    }

    /**
     * Adds a MAJOR severity notification when a TLS certificate is about to expire.
     *
     * @param string $domain Domain name whose certificate is expiring.
     * @param int $daysRemaining Number of days until certificate expiry.
     * @return void
     */
    public function notifyExpiringCertificate(string $domain, int $daysRemaining): void
    {
        /** @var Inbox $inbox */
        $inbox = $this->inboxFactory->create();
        $inbox->addNotice(
            sprintf('SSL-Zertifikat läuft in %d Tagen ab', $daysRemaining),
            sprintf(
                'Das TLS-Zertifikat für %s läuft in %d Tagen ab. Erneuerung im Hosting-Panel prüfen.',
                $domain,
                $daysRemaining
            ),
            sprintf('https://%s', $domain),
            true
        );
    }
}

Die Methode addNotice() auf dem Inbox-Model ist ein Komfort-Wrapper, der intern NOTICE_SEVERITY_MAJOR setzt und die Zeile in einem Schritt anlegt und speichert. Wer den Schweregrad explizit steuern will, etwa für eine CRITICAL-Meldung bei einem fehlgeschlagenen Zahlungs-Gateway, setzt severity direkt über setSeverity(Inbox::NOTICE_SEVERITY_CRITICAL) vor dem Aufruf von save(). Wichtig für die Entkopplung: Das Repository sollte hinter einem eigenen Interface im Api-Namespace liegen, damit andere Module die Benachrichtigungslogik nutzen können, ohne eine harte Abhängigkeit auf die konkrete Implementierung einzugehen. Das ist derselbe Service-Contract-Gedanke, den Magento bei Order-Repository oder Customer-Repository konsequent verfolgt.

4. Cron-Job als Auslöser für Benachrichtigungen

Die meisten sinnvollen Admin-Benachrichtigungen entstehen nicht synchron während eines Kundenrequests, sondern asynchron über einen Cron-Job, der eine Bedingung periodisch prüft. Ein Zertifikatsablauf, ein niedriger Lagerbestand oder eine fehlgeschlagene nächtliche API-Synchronisation sind klassische Kandidaten für einen täglichen oder stündlichen Check. Die Registrierung erfolgt über crontab.xml im eigenen Modul, mit einer Cron-Group, die entweder auf die Standard-Gruppe default zielt oder auf eine dedizierte Gruppe, falls die Prüfung ressourcenintensiv ist und isoliert laufen soll.

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Cron:etc/crontab.xsd">
    <group id="default">
        <job name="mironsoft_notificationhub_check_certificates"
             instance="Mironsoft\NotificationHub\Cron\CheckCertificateExpiry"
             method="execute">
            <schedule>0 6 * * *</schedule>
        </job>
        <job name="mironsoft_notificationhub_check_stock"
             instance="Mironsoft\NotificationHub\Cron\CheckLowStock"
             method="execute">
            <schedule>0 * * * *</schedule>
        </job>
    </group>
</config>

Der Cron-Job selbst injiziert das oben gezeigte Repository beziehungsweise Notifier-Interface und ruft es nach der Prüfung der Bedingung auf. Entscheidend für ein robustes Notification-System ist, Duplikate zu vermeiden: Ein Cron-Job, der stündlich läuft, soll nicht bei jedem Lauf eine neue Zeile in die Inbox schreiben, solange sich der Zustand nicht geändert hat. In der Praxis löst man das über eine Prüfung, ob innerhalb der letzten 24 Stunden bereits eine Benachrichtigung mit demselben notification_type-Wert existiert, bevor eine neue angelegt wird. Der Resource-Model-Collection-Filter addFieldToFilter('notification_type', ['eq' => $type]) kombiniert mit einem Datumsfilter auf date_added verhindert so eine Flut identischer Meldungen in der Glocke.

5. System Messages per di.xml registrieren

System Messages unterscheiden sich fundamental von Inbox-Benachrichtigungen: Sie werden nicht in einer Tabelle gespeichert, sondern bei jedem Backend-Request neu ausgewertet. Eine Implementierung von Magento\Framework\Notification\MessageInterface prüft in der Methode isDisplayed() live, ob eine Bedingung aktuell zutrifft, etwa ob der Cache-Modus auf Entwicklung steht oder ob eine Pflichtkonfiguration fehlt. Die Methode getSeverity() gibt eine der Konstanten aus MessageInterface::SEVERITY_MINOR, SEVERITY_MAJOR oder SEVERITY_CRITICAL zurück und bestimmt, ob das Banner gelb oder rot erscheint.

<?php

declare(strict_types=1);

namespace Mironsoft\NotificationHub\Model\System\Message;

use Magento\Framework\Notification\MessageInterface;
use Magento\Framework\UrlInterface;
use Mironsoft\NotificationHub\Model\ApiSyncStatusCheckerInterface;

/**
 * System message shown when the last supplier API synchronization failed.
 */
class ApiSyncFailure implements MessageInterface
{
    /**
     * @param ApiSyncStatusCheckerInterface $statusChecker Checks the persisted state of the last sync run.
     * @param UrlInterface $urlBuilder Builds the admin URL for the sync monitor page.
     */
    public function __construct(
        private readonly ApiSyncStatusCheckerInterface $statusChecker,
        private readonly UrlInterface $urlBuilder
    ) {
    }

    /**
     * Returns a unique identifier for this system message.
     *
     * @return string
     */
    public function getIdentity(): string
    {
        return 'mironsoft_notificationhub_api_sync_failure';
    }

    /**
     * Determines whether the banner should currently be shown.
     *
     * @return bool
     */
    public function isDisplayed(): bool
    {
        return $this->statusChecker->hasFailedSync();
    }

    /**
     * Returns the banner text including a link to the monitor page.
     *
     * @return string
     */
    public function getText(): string
    {
        $url = $this->urlBuilder->getUrl('mironsoft_notificationhub/sync/monitor');
        return sprintf('Die letzte API-Synchronisation ist fehlgeschlagen. <a href="%s">Details ansehen</a>', $url);
    }

    /**
     * Returns the severity level controlling banner color.
     *
     * @return int
     */
    public function getSeverity(): int
    {
        return MessageInterface::SEVERITY_MAJOR;
    }
}

Die Registrierung dieser Klasse erfolgt nicht direkt, sondern über einen virtuellen Type in di.xml, der in die von Magento verwaltete MessageList eingehängt wird. Diese Liste durchläuft beim Rendern des Backend-Headers alle registrierten Messages und ruft isDisplayed() auf jeder einzelnen auf.

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <type name="Magento\Framework\Notification\MessageList">
        <arguments>
            <argument name="messages" xsi:type="array">
                <item name="mironsoft_api_sync_failure" xsi:type="string">
                    Mironsoft\NotificationHub\Model\System\Message\ApiSyncFailure
                </item>
            </argument>
        </arguments>
    </type>
</config>

Ein wichtiger Unterschied zur Inbox: System Messages werden bei jedem Request neu ausgewertet und haben keinen persistenten Zustand. Das macht sie ideal für Bedingungen, die sich schnell ändern können, etwa ob ein externer Dienst gerade erreichbar ist. Für historische Nachvollziehbarkeit, wer wann über welchen Zustand informiert wurde, ist die Inbox dagegen das richtige Werkzeug, weil sie einen dauerhaften Datensatz mit Zeitstempel erzeugt.

6. System Message vs. Inbox-Notification: Wann welcher Mechanismus

Die Entscheidung zwischen System Message und Inbox-Notification hängt maßgeblich von der Dringlichkeit und der gewünschten Sichtbarkeit ab. Eine System Message erscheint sofort und für jeden Administrator sichtbar als Banner, unabhängig davon, ob die Glocke überhaupt geöffnet wird. Sie eignet sich für Zustände, die eine unmittelbare Reaktion erfordern und bei denen ein Übersehen inakzeptabel wäre, etwa eine fehlende Pflichtkonfiguration nach einem Deployment. Eine Inbox-Benachrichtigung dagegen ist unaufdringlicher: Sie erhöht lediglich den Zähler an der Glocke und wird erst beim aktiven Öffnen sichtbar, eignet sich also besser für Informationen, die zur Kenntnis genommen werden sollen, aber keine sofortige Unterbrechung rechtfertigen.

Ein weiterer praktischer Unterschied liegt in der Historisierung. Da Inbox-Einträge in einer Tabelle liegen, lässt sich jederzeit nachvollziehen, wie viele Admin-Benachrichtigungen welchen Typs in einem bestimmten Zeitraum aufgetreten sind, etwa für ein internes Reporting über Systemstabilität. System Messages hinterlassen dagegen keine Spur, sobald die zugrunde liegende Bedingung nicht mehr zutrifft, da sie nicht persistiert werden. Für Audit-Anforderungen oder Compliance-Nachweise ist deshalb häufig eine Kombination sinnvoll: eine System Message für die sofortige Sichtbarkeit und parallel ein Inbox-Eintrag für die dauerhafte Dokumentation desselben Ereignisses.

7. ACL-Steuerung: Wer sieht welche Benachrichtigung

Sowohl Inbox-Benachrichtigungen als auch System Messages werden im Backend grundsätzlich für jeden angemeldeten Administrator gerendert, es sei denn, die Anzeigelogik prüft explizit die Berechtigungen des aktuellen Benutzers. Für Backend-Benachrichtigungen, die nur für bestimmte Rollen relevant sind, etwa Lagerbestandswarnungen nur für die Rolle Einkauf, injiziert man in die isDisplayed()-Methode der System Message zusätzlich Magento\Framework\AuthorizationInterface und prüft mit isAllowed('Mironsoft_NotificationHub::stock_alerts'), ob der aktuell eingeloggte Admin-User über die entsprechende ACL-Ressource verfügt.

Die ACL-Ressource selbst wird wie bei jedem Backend-Menüpunkt in acl.xml im eigenen Modul deklariert und unterhalb von Magento_Backend::admin eingehängt. Für Inbox-Benachrichtigungen ist eine feingranulare ACL-Filterung aufwendiger, da die Standard-Controller von Magento_AdminNotification keine Typ-basierte Berechtigungsprüfung vorsehen. Wer das benötigt, erweitert entweder den Controller per Plugin und filtert die Collection vor der Ausgabe, oder trennt kritische, rollenspezifische Meldungen konsequent über System Messages ab, bei denen die ACL-Prüfung pro Klasse einfach zu implementieren ist. In der Praxis hat sich bewährt, für weit verteilte, rollenübergreifende Informationen die Inbox zu nutzen und für rollenspezifische, dringende Hinweise System Messages mit expliziter ACL-Prüfung.

8. ViewModel für eigene Benachrichtigungs-UI

Wer eigene Admin-Benachrichtigungen nicht nur über die Standard-Glocke ausgeben, sondern zusätzlich in einer eigenen Übersichtsseite im Backend darstellen möchte, etwa einem Dashboard-Widget mit den letzten zehn kritischen Meldungen, sollte konsequent auf ein ViewModel setzen statt auf eine Block-Klasse mit Geschäftslogik. Das ViewModel implementiert Magento\Framework\View\Element\Block\ArgumentInterface und wird per Layout-XML an das Template gebunden, wodurch die Darstellung sauber von der Datenermittlung getrennt bleibt.

<?php

declare(strict_types=1);

namespace Mironsoft\NotificationHub\ViewModel;

use Magento\Framework\View\Element\Block\ArgumentInterface;
use Magento\AdminNotification\Model\ResourceModel\Inbox\CollectionFactory;

/**
 * Provides recent critical inbox notifications to the dashboard widget template.
 */
class RecentCriticalNotifications implements ArgumentInterface
{
    /**
     * @param CollectionFactory $collectionFactory Factory for the Inbox collection.
     */
    public function __construct(
        private readonly CollectionFactory $collectionFactory
    ) {
    }

    /**
     * Returns the ten most recent critical severity notifications.
     *
     * @return \Magento\AdminNotification\Model\Inbox[]
     */
    public function getRecentCritical(): array
    {
        $collection = $this->collectionFactory->create();
        $collection->addFieldToFilter('severity', ['eq' => 3])
            ->setOrder('date_added', 'DESC')
            ->setPageSize(10);

        return $collection->getItems();
    }
}

Diese Trennung zahlt sich besonders aus, wenn dieselbe Datenlogik später an mehreren Stellen benötigt wird, etwa zusätzlich in einem REST-Endpoint für ein externes Monitoring-Dashboard. Da das ViewModel keine Abhängigkeit zu einer Block-Klasse hat, lässt es sich ohne Änderungen in einem Service-Layer wiederverwenden. Für die ACL-Filterung im Dashboard-Widget wird dem ViewModel zusätzlich AuthorizationInterface injiziert, sodass nur Benutzer mit passender Berechtigung die entsprechenden Admin-Benachrichtigungen im Widget sehen.

9. Benachrichtigungskanäle im Vergleich

Ein eigenes Notification-System muss nicht ausschließlich auf Magento_AdminNotification aufsetzen. Je nach Dringlichkeit und Zielgruppe kommen auch E-Mail-Benachrichtigungen oder Slack-Webhooks infrage, die parallel zur Backend-Anzeige ausgelöst werden. Die folgende Tabelle vergleicht die vier gängigsten Kanäle für operative Ereignisse in einem Magento-Projekt.

In der Praxis ergänzen sich diese Kanäle. Eine kritische Admin-Benachrichtigung über einen fehlgeschlagenen Zahlungs-Sync sollte idealerweise gleichzeitig als System Message im Backend erscheinen, als Inbox-Eintrag für die Historie gespeichert und zusätzlich per Slack-Webhook an das verantwortliche Team gemeldet werden. Für rein informative Hinweise reicht dagegen ein einzelner Inbox-Eintrag völlig aus, ohne zusätzliche Kanäle zu belasten.

10. Zusammenfassung

Ein eigenes Notification-System in Magento 2 muss das Rad nicht neu erfinden. Magento_AdminNotification liefert mit der Inbox-Tabelle, den drei Schweregraden und dem Controller-Unterbau bereits alles, was für dauerhafte, historisierte Admin-Benachrichtigungen nötig ist. Ergänzt um System Messages für sofort sichtbare Banner und einen Cron-Job als Auslöser entsteht ein vollständiges Benachrichtigungssystem, das sich sauber in Service Contracts, Repositories und ViewModels kapseln lässt, statt Business-Logik direkt in Cron-Klassen oder Block-Dateien zu verstreuen.

Die Wahl zwischen Inbox-Notification und System Message ist keine reine Geschmacksfrage, sondern hängt direkt von Dringlichkeit und gewünschter Historisierung ab. ACL-Regeln stellen sicher, dass rollenspezifische Backend-Benachrichtigungen nur bei den richtigen Administratoren landen, während dismissible und persistente Flags steuern, ob eine Meldung dauerhaft im System bleibt oder weggeklickt werden darf. Wer diese Bausteine konsequent kombiniert, erhält ein Notification-System, das sich nahtlos in die gewohnte Magento-Backend-Oberfläche einfügt, statt eine parallele, für Administratoren fremde UI aufzubauen.

11. FAQ: Eigene Admin-Benachrichtigungen im Backend registrieren