Überblick

Das Problem

Eine gewachsene Contao-Website verschickt mehr E-Mails, als irgendjemand im Kopf hat: die Bestätigung des Kontaktformulars, die Meldung an den Vertrieb, die Registrierungsmail, das neue Passwort, der Hinweis auf einen Kommentar, die Bestätigung der Newsletter-Anmeldung. Jede dieser Nachrichten wurde irgendwann einmal von jemand anderem eingerichtet – im Formulargenerator, in einem Frontend-Modul, in einer Erweiterung oder direkt im Code. Der Text steht an sechs Stellen, das Layout an keiner.

• Niemand weiß, ob eine Mail angekommen ist. Ein Kunde ruft an und sagt, er habe nichts erhalten. Die Antwort darauf steht bestenfalls in var/logs/, also praktisch nirgends.
• Änderungen am Text sind eine Suche. Wer die Absenderadresse oder den Rechtshinweis im Fuß anpassen will, muss erst herausfinden, welche der Mails überhaupt wo konfiguriert ist.
• Jede Mail sieht anders aus. Kopf, Fuß, Farben und Schrift werden pro Nachricht kopiert. Nach zwei Jahren gleicht keine Mail der anderen und keine dem Erscheinungsbild der Website.
• Eingefügte HTML-Designs brechen in Outlook. Ein Design, das im Browser korrekt aussieht, wird in Outlook und Gmail unbrauchbar, sobald das CSS in einem <style>-Block steht statt in style-Attributen.
• Testen heißt: das echte Ereignis auslösen. Um eine Registrierungsmail zu prüfen, wird ein Testkonto registriert – mit allen Nebenwirkungen, die das hat.
• Mehrsprachigkeit wird zur Kopie. Für jede weitere Sprache entsteht eine zweite Konfiguration, die ab dem Tag ihrer Anlage auseinanderläuft.

Am härtesten trifft das die Redaktion und den Support: Die eine darf Texte nicht ändern, ohne einen Entwickler zu fragen, der andere kann eine einfache Frage – „ist die Mail raus?“ – nicht beantworten.

Die Lösung

Alle Benachrichtigungen einer Contao-Installation werden an einer Stelle im Backend beschrieben, dort getestet und dort nachvollzogen – unabhängig davon, was sie auslöst.

Die Suite trennt drei Dinge, die sonst vermischt sind: Eine Benachrichtigung beschreibt den Anlass („Kontaktformular abgeschickt“). Ihre Nachrichten beschreiben die konkreten Aussendungen, je Sprache eine. Ein Absender beschreibt den Weg, über den ausgeliefert wird – E-Mail, Webhook oder Datei. Ein gemeinsames Layout liefert den gestalteten Rahmen, und das Versandprotokoll hält fest, was tatsächlich passiert ist.

Den oben genannten Kosten stehen damit konkrete Funktionen gegenüber:

• Versandprotokoll – jeder Versuch mit Empfänger, Betreff, Status und Fehlertext; fehlgeschlagene Einträge lassen sich erneut senden.
• Benachrichtigungen und Nachrichten – ein Modul für alle Texte, mit Veröffentlichungszeitraum je Nachricht.
• E-Mail-Layouts, Designs und Branding – 20 mitgelieferte Designs, die Logo, Markenfarbe und Firmenangaben aus einem einzigen Datensatz beziehen.
• CSS-Inlining – Regeln eines Layouts werden vor dem Versand auf die Elemente übertragen.
• Vorschau und Testversand – ohne das auslösende Ereignis.
• Nachrichten je Sprache unter derselben Benachrichtigung, mit einer Fallback-Nachricht.
• Absender vom Typ Webhook / JSON – für Slack, Microsoft Teams, Google Chat, Zapier und beliebige HTTPS-Endpunkte.

Wann das Paket passt

Teil 1 — Einrichtung

Der Weg von der Installation bis zur ersten versendeten Benachrichtigung:

1. Voraussetzungen prüfen
2. Vor der Installation: Sicherung und Entscheidungen
3. Installation über den Contao Manager oder über Composer
4. Installation überprüfen
5. Lizenz aktivieren
6. Konfiguration (optional)
7. Die erste Benachrichtigung anlegen

Voraussetzungen

Vor der Installation

1. Datensicherung anlegen – Datenbank und Dateisystem. Die Installation legt neue Tabellen an; ein Rückweg ohne Sicherung ist unangenehm.
2. Testumgebung bevorzugen – richten Sie die Suite zuerst auf einem Test- oder Staging-System ein. Beachten Sie dabei, dass eine Lizenz an Hostnamen gebunden ist: Test-, Staging- und Produktivsystem benötigen jeweils eine für ihren Hostnamen gültige Lizenz.
3. Domain auf der Startseite prüfen – im Seitenbaum muss auf der Startseite eine Domain hinterlegt sein. Ohne konfigurierte Domain lässt sich die Lizenz nicht aktivieren.
4. Schreibrechte prüfen – siehe Tabelle unten.
5. Entscheiden, ob Inhalte protokolliert werden dürfen – das Versandprotokoll speichert standardmäßig Betreff und Inhalt jeder Nachricht, damit ein erneuter Versand möglich ist. Auf Installationen, die keine personenbezogenen Daten vorhalten dürfen, wird das abgeschaltet (siehe Konfiguration).

Installation über den Contao Manager

So installieren Sie das Paket

1. Contao Manager öffnen und anmelden.
2. Den Bereich Entdecken öffnen. Neue Pakete werden immer dort gesucht und hinzugefügt; der Bereich Pakete daneben zeigt unter Installierte Pakete nur, was bereits vorhanden ist. Entdecken ist zugleich die Startansicht des Managers.
3. Über Pakete suchen nach vtinnovations/centralized-notification-suite suchen und beim Treffer Paket hinzufügen wählen.
4. Die Änderungen anwenden. Der Contao Manager installiert das Paket und aktualisiert den Autoloader.
5. In den Bereich Systemwartung wechseln, dort Datenbank-Migrationen und -Backups öffnen und Datenbank prüfen ausführen. Die angezeigten Datenbank-Änderungen bestätigen – sie legen die Tabellen der Suite an.
6. Ebenfalls unter Systemwartung den Anwendungs-Cache leeren (in der Navigation auch als Cache erneuern zu finden).
7. Weiter mit Installation überprüfen.

Installation über Composer

Die Alternative für Installationen, die von der Kommandozeile aus gepflegt werden:

composer require vtinnovations/centralized-notification-suite
vendor/bin/contao-console contao:migrate

Auf einer Managed Edition richtet contao:setup anschließend die Verzeichnisse und symbolischen Verknüpfungen ein:

vendor/bin/contao-console contao:setup

Aktualisierung auf eine neuere Version:

composer update vtinnovations/centralized-notification-suite
vendor/bin/contao-console contao:migrate
vendor/bin/contao-console cache:clear --env=prod

Installation überprüfen

Zwei Prüfungen genügen. Auf der Kommandozeile:

vendor/bin/contao-console debug:container --parameter=kernel.bundles | grep CentralizedNotificationSuite
vendor/bin/contao-console list notification

Der zweite Befehl muss die vier Befehle der Suite auflisten: notification:send, notification:install-layouts, notification:install-emails und notification:import-nc.

Im Backend erscheint in der Navigation eine neue Gruppe Centralized Notification Suite – direkt oberhalb der Gruppe System, nicht am Ende des Menüs – mit sechs Modulen in dieser Reihenfolge:

Die ersten fünf Module folgen der normalen Contao-Rechteverwaltung und lassen sich je Benutzergruppe freigeben. Das Modul SMTP-Konfiguration ist Administratoren vorbehalten; alle anderen Benutzer sehen dort „Zugriff verweigert. Nur für Administratoren.“

Lizenz aktivieren

Die Suite setzt eine aktivierte Lizenz voraus. Ohne sie wird nichts versendet und nichts in die Warteschlange gestellt – die Installation verhält sich genau so, als wäre das Paket nicht installiert. Benachrichtigungen, Nachrichten, Layouts, Branding und Versandprotokoll bleiben dabei unverändert erhalten.

Das Produkt wird mit einer kostenfreien, unbefristeten Lizenz ausgeliefert. „Kostenfrei“ bezieht sich ausschließlich auf den Preis: Eine von V-T.ONE ausgestellte Lizenz muss aktiviert sein. Es gibt genau diese eine Stufe – keine Testphase und keine zweite, größere Ausbaustufe.

Verwaltet wird sie unter Contao → Einstellungen im Abschnitt V-T.ONE Licence management. Das ist der gemeinsame Abschnitt aller V-T.ONE-Pakete: Jedes Paket zeigt dort eine eigene Karte, überschrieben mit seinem Produktnamen – hier Centralized Notification Suite.

So aktivieren Sie die Lizenz

1. Stellen Sie sicher, dass im Seitenbaum auf der Startseite die Domain hinterlegt ist, für die Ihr Schlüssel ausgestellt wurde.
2. Melden Sie sich als Benutzer an, der das Modul Einstellungen öffnen darf. In der Praxis ist das ein Administrator.
3. Öffnen Sie Einstellungen und scrollen Sie zum Abschnitt V-T.ONE Licence management, dort zur Karte Centralized Notification Suite. Die erste Zeile der Karte zeigt den aktuellen Zustand: Lizenz aktiv oder Keine aktive Lizenz.
4. Tragen Sie den Schlüssel in das Feld Lizenzschlüssel ein. Der Platzhalter im Feld lautet XXXXX-XXXXX-XXXXX-XXXXX.
5. Klicken Sie Lizenz prüfen und aktivieren. Der Server nimmt dafür selbst eine ausgehende HTTPS-Verbindung auf – nicht Ihr Browser. Ein Firewall-Regelwerk, das ausgehende Verbindungen unterbindet, verhindert die Aktivierung.
6. Bei Erfolg erscheint die Meldung „Die Lizenz wurde aktiviert.“ und die Karte zeigt Lizenz aktiv sowie die Angaben Paket, Lizenzierter Host, Abgedeckte Hosts, Version und Laufzeit (bei unbefristeten Lizenzen: Unbefristet).
7. Das Schlüsselfeld ist danach wieder leer. Der hinterlegte Schlüssel wird in der Oberfläche nicht erneut ausgegeben – auch nicht unmittelbar nach der Aktivierung. Das ist erwartetes Verhalten und kein Zeichen dafür, dass nichts gespeichert wurde; maßgeblich ist die Statuszeile.

Zwei weitere Schaltflächen stehen jederzeit zur Verfügung:

Konfiguration

Die Suite arbeitet ohne Konfigurationsdatei. Wer die Voreinstellungen ändern will, legt sie in config/config.yaml ab. Alle Werte sind optional; die gezeigten entsprechen den Voreinstellungen.

# config/config.yaml
centralized_notification_suite:
    log:
        enabled: true
        store_body: true
        retention_days: 90
        max_attempts: 3
        retry_failed: true
    mailer:
        php_binary: ''
        process_timeout: 120
        memory_limit: '-1'

Nach jeder Änderung an dieser Datei den Cache leeren:

vendor/bin/contao-console cache:clear --env=prod

Die erste Benachrichtigung

Der kürzeste Weg zu einem überprüfbaren Ergebnis: ein Absender, eine Benachrichtigung, eine Nachricht, ein Testversand.

So richten Sie die erste Benachrichtigung ein

1. Öffnen Sie Absender und legen Sie einen neuen Eintrag an. Vergeben Sie einen Titel, wählen Sie als Typ den Eintrag E-Mail und tragen Sie unter Absenderadresse die Adresse ein, von der gesendet wird. Speichern.
2. Öffnen Sie Benachrichtigungen und legen Sie einen Eintrag an. Titel vergeben; das Feld Alias leer lassen, dann wird es aus dem Titel erzeugt. Unter Ausgelöst durch wählen Sie den Anlass, zum Beispiel Ein Formularversand.
3. Speichern. Die Auswahl unter Ausgelöst durch bestimmt, welche Tokens Ihnen beim Bearbeiten der Nachricht angeboten werden und an welchen Stellen diese Benachrichtigung überhaupt zur Auswahl steht.
4. Klicken Sie in der Liste auf Nachrichten bearbeiten und legen Sie eine Nachricht an.
5. Wählen Sie im Abschnitt Absender und Sprache den eben angelegten Absender und die Sprache. Setzen Sie den Haken bei Fallback-Nachricht, solange es nur eine Nachricht gibt – sonst wird sie nur bei exakt passender Sprache verwendet.
6. Tragen Sie unter Betreff und im Abschnitt HTML den Inhalt ein und füllen Sie unter Empfänger mindestens eine Adresse aus. Das Hilfe-Symbol an den Inhaltsfeldern zeigt alle verfügbaren Tokens.
7. Speichern und in die Liste zurückkehren. Klicken Sie dort auf Vorschau, um das fertige Ergebnis mit Beispielwerten zu sehen.
8. Klicken Sie auf Test senden, tragen Sie unter Senden an Ihre eigene Adresse ein und senden Sie ab. Anschließend erscheint „Testnachricht an … gesendet. Das Ergebnis steht im Versandprotokoll.“
9. Öffnen Sie Versandprotokoll und prüfen Sie den Status des Eintrags.
10. Verknüpfen Sie die Benachrichtigung zuletzt mit ihrem Auslöser – im Formulargenerator über das Feld Benachrichtigungen, in einem Mitglieder- oder Newsletter-Modul über das gleichnamige Feld, oder aus eigenem Code über den Alias.

vendor/bin/contao-console notification:install-layouts
vendor/bin/contao-console notification:install-emails

Teil 2 — Funktionen im Detail

Benachrichtigungen

Eine Benachrichtigung beschreibt den Anlass, nicht die Mail. Sie liegt im Modul Benachrichtigungen und hat genau einen Abschnitt: Titel und Alias.

So legen Sie eine Benachrichtigung an

1. Benachrichtigungen öffnen und Neue Benachrichtigung wählen.
2. Titel eintragen – der Name, unter dem die Benachrichtigung in allen Auswahllisten erscheint.
3. Alias leer lassen, außer Sie brauchen einen bestimmten Bezeichner. Aus dem Titel wird dann ein eindeutiger Alias erzeugt.
4. Unter Ausgelöst durch den Typ wählen. Die Seite lädt danach neu.
5. Speichern. Über Nachrichten bearbeiten geht es zu den Aussendungen, über Einstellungen bearbeiten zurück zu diesem Formular.

Nachrichten und Sprachen

Eine Nachricht ist die konkrete Aussendung. Sie liegt unterhalb ihrer Benachrichtigung und wird über Nachrichten bearbeiten erreicht. Das Formular hat sechs Abschnitte in dieser Reihenfolge: Absender und Sprache, Nur-Text, HTML, Empfänger, Anhänge und Veröffentlichung.

So legen Sie eine Nachricht an

1. In der Benachrichtigungsliste auf Nachrichten bearbeiten klicken, dann Neue Nachricht.
2. Absender wählen. Angeboten werden ausschließlich veröffentlichte Absender – ein unveröffentlichter würde eine Nachricht erzeugen, die konfiguriert aussieht und nie sendet.
3. Sprache wählen. Maßgeblich ist später die Sprache der Anfrage, in der die Benachrichtigung ausgelöst wird.
4. Fallback-Nachricht setzen, wenn diese Nachricht einspringen soll, sobald keine Nachricht zur angeforderten Sprache passt.
5. Betreff eintragen. Tokens sind erlaubt; das Hilfe-Symbol am Feld listet alle Tokens dieser Benachrichtigung.
6. Im Abschnitt HTML entscheiden, ob der Inhalt aus Bausteinen aufgebaut oder als Eigenes HTML geschrieben wird. Optional ein Layout zuweisen.
7. Empfänger eintragen – eine oder mehrere Adressen, durch Komma oder Semikolon getrennt; Tokens sind erlaubt. Bei Bedarf CC, BCC und Antwort an ausfüllen.
8. Speichern. Anschließend stehen in der Liste Vorschau und Test senden zur Verfügung, im Bausteinmodus zusätzlich der Einstieg in die untergeordneten Bausteine.

Die Liste kennzeichnet Nachrichten, die nicht zugestellt werden können, mit dem Grund – zum Beispiel „Der zugewiesene Absender existiert nicht mehr, diese Nachricht wird nicht versendet.“, „Der Absender „…“ ist nicht veröffentlicht, diese Nachricht wird nicht versendet.“ oder „Diese Nachricht hat keine Empfänger, sie wird nicht versendet.“

Inhalt aus Bausteinen

Im Modus Bausteine erhält die Nachricht eine untergeordnete Liste, in der der Inhalt aus einzelnen Elementen zusammengesetzt wird. Das Feld HTML entfällt dann aus dem Formular der Nachricht. Bausteine lassen sich per Drag & Drop sortieren und einzeln ein- und ausblenden.

So bauen Sie einen Nachrichteninhalt auf

1. In der Nachricht das Feld Inhalt auf Bausteine stellen und speichern.
2. In der Nachrichtenliste den Einstieg in die untergeordneten Bausteine wählen und Neuer Baustein klicken.
3. Unter Bausteintyp den gewünschten Typ wählen. Die Seite lädt neu und zeigt die Felder dieses Typs.
4. Den Inhalt erfassen. Tokens wie ##name## sind in Überschrift, Text, Linktext, Linkziel, den Zeilen der Detailtabelle und im eigenen HTML erlaubt.
5. Im Abschnitt Abstände bei Bedarf Ausrichtung und Abstand unten (px) setzen.
6. Speichern. Der Baustein erscheint in der Liste mit einer Vorschaukarte.
7. Weitere Bausteine anlegen und per Drag & Drop in die gewünschte Reihenfolge bringen.
8. Über Vorschau an der Nachricht das Gesamtergebnis prüfen.

Tokens

##token## steht in Betreff, Inhalt, Adressfeldern und in den Bausteinen zur Verfügung. Contao-Insert-Tags wie https://www.v-t.one oder funktionieren ebenfalls, ebenso {if} / {else} / {endif}.

So finden Sie die verfügbaren Tokens

1. Die Nachricht öffnen, deren Tokens Sie brauchen.
2. Auf das Hilfe-Symbol neben Betreff, Nur-Text oder HTML klicken – oder, im Bausteinmodus, neben den Feldern eines Bausteins.
3. Das Fenster listet die Tokens in zwei Spalten: Token und Enthält. Der erste Block ist mit Für jede Benachrichtigung verfügbar überschrieben; darunter folgen die Tokens des Typs dieser Benachrichtigung.
4. Den Token-Namen in das Feld übernehmen, eingefasst in doppelte Rautezeichen.

Immer verfügbar: ##admin_email##, ##date##, ##time##, ##datim##, ##host##, ##url##, ##page_id##, ##page_title##, ##page_url##.

Bei Formular-Benachrichtigungen zusätzlich jedes übermittelte Feld unter dem „Namen“, den es im Formulargenerator trägt – und:

Mitglieder-Benachrichtigungen erhalten ##member_id##, ##member_firstname##, ##member_lastname##, ##member_email##, ##member_username##, jedes weitere Mitgliederfeld als ##member_<feld>## sowie ##member_event## – mit einem der Werte registration, activation, profile_updated, password_changed oder account_closed.

Kommentar-Benachrichtigungen erhalten ##comment_name##, ##comment_email##, ##comment_comment##, ##comment_source##, ##comment_published## und ##comment_awaiting_moderation##. Newsletter-Benachrichtigungen erhalten ##recipient_email##, ##newsletter_event## (subscribed oder unsubscribed), ##newsletter_channels## und ##newsletter_channel_ids##.

E-Mail-Layouts und Designs

Ein Layout ist der gestaltete Rahmen, den sich mehrere Nachrichten teilen. Es liegt im Modul E-Mail-Layouts und wird an der Nachricht im Feld Layout zugewiesen. Drei Betriebsarten stehen zur Wahl, gesteuert über Layout-Art:

So erstellen Sie ein Layout

1. E-Mail-Layouts öffnen und Neues Layout wählen.
2. Titel vergeben, z. B. „Standard-Layout“.
3. Optional einen Vorschautext eintragen – „die versteckte Zeile, die die meisten E-Mail-Programme neben dem Betreff im Postfach anzeigen“. Tokens sind erlaubt.
4. Layout-Art wählen. Die Seite lädt neu und zeigt die passenden Felder.
5. Bei Ein fertiges Design: unter Design eines der 20 mitgelieferten Designs wählen. Die Auswahl ist nach Gruppen sortiert – Card, Brand bar, Dark, Minimal, Transactional, Announcement und Editorial. Voreingestellt ist Card – left logo.
6. Bei den beiden anderen Arten: das Markup einfügen und im Abschnitt Styles das CSS hinterlegen – ohne <style>-Tags.
7. CSS inline schreiben aktiviert lassen. „Lassen Sie das aktiviert, außer Sie wissen, dass das Programm der Empfänger Style-Blöcke unterstützt.“
8. Veröffentlicht setzen und speichern. Erst dann steht das Layout im Feld Layout einer Nachricht zur Auswahl.
9. An einer Nachricht zuweisen und über Vorschau prüfen – auch in der Ansicht Mobil.

Die Designnamen sind englisch beschriftet, weil sie Gestaltungsvarianten benennen: Card – centred logo, Card – left logo, Card – square corners, Card – outlined, Brand bar – centred logo, Brand bar – left logo, Brand bar – dark footer, Dark header, Dark header and footer, Minimal – hairline rule, Minimal – wordmark only, Minimal – no header, Compact – tight spacing, Transactional – plain and narrow, Transactional – tinted panel, Receipt – boxed, monospaced figures, Announcement – wide, centred, Announcement – tinted background, Newsletter – serif headings und Editorial – serif, dark footer.

Zwei fertige Layouts lassen sich mit einem Befehl einspielen – Transactional (plain, no images) und Branded (logo header, footer). Beide werden als Vollständiges HTML-Dokument angelegt und können anschließend bearbeitet werden:

vendor/bin/contao-console notification:install-layouts
vendor/bin/contao-console notification:install-layouts --list    # nur anzeigen
vendor/bin/contao-console notification:install-layouts --force   # vorhandene überschreiben

Branding

Das Modul Branding hält genau einen Datensatz: Logo, Markenfarbe und Firmenangaben, aus denen jedes fertige Design seine Gestaltung ableitet. Beim Öffnen des Moduls landen Sie direkt im Formular; eine Liste gibt es nicht, und es lässt sich weder ein zweiter Datensatz anlegen noch dieser löschen.

So hinterlegen Sie Ihr Branding

1. Branding öffnen – das Formular erscheint unmittelbar.
2. Im Abschnitt Logo über die Dateiauswahl eine Datei wählen. Zulässig sind ausschließlich JPG, PNG und GIF.
3. Logobreite (px) setzen. „120–180 passt für die meisten Logos.“
4. Im Abschnitt Farbe die Markenfarbe als Hex-Wert eintragen oder über den Farbwähler bestimmen.
5. Im Abschnitt Firmenangaben Firmenname, Website, Kontaktadresse und Postanschrift ausfüllen.
6. Im Abschnitt Fußzeile optional eine Fußnote ergänzen.
7. Speichern und über die Vorschau einer Nachricht mit Design-Layout kontrollieren.

Absender (Gateways)

Ein Absender beschreibt den Weg, über den eine Nachricht ausgeliefert wird. Das Modul Absender kennt drei Typen; die Felder unterhalb von Typ wechseln, sobald der Typ gewählt ist.

So legen Sie einen Absender an

1. Absender öffnen und Neuer Absender wählen.
2. Titel eintragen – der Name, unter dem der Absender in den Nachrichten erscheint.
3. Typ wählen. Die Seite lädt neu und zeigt den passenden Abschnitt: E-Mail-Einstellungen, Webhook-Einstellungen oder Datei-Einstellungen.
4. Die Felder dieses Typs ausfüllen (siehe Tabellen unten).
5. Veröffentlicht setzen und speichern. Nur veröffentlichte Absender werden im Feld Absender einer Nachricht angeboten.
6. Den Absender an einer Nachricht zuweisen und mit Test senden prüfen.

Typ E-Mail – versendet über Symfony Mailer:

Typ Webhook / JSON (Slack, Teams, Zapier, …) – sendet an einen HTTPS-Endpunkt:

Das Hilfe-Symbol am Feld JSON-Payload öffnet einen Assistenten mit fertigen Vorlagen für Slack (Block Kit), Microsoft Teams (Workflows-Webhook mit Adaptive Card) und Google Chat sowie einer Liste der im Payload verwendbaren Tokens: ##subject##, ##text##, ##html##, ##recipients##, ##alias## und ##reference## – letzteres „eine eindeutige ID dieses Versands, nützlich zum Abgleich mit dem Versandprotokoll“.

Typ Datei (schreibt auf die Festplatte statt zu senden) – für Entwicklung und Abnahme:

SMTP-Konfiguration

Das Modul SMTP-Konfiguration hinterlegt die Zugangsdaten, über die die gesamte Website versendet – nicht nur die Benachrichtigungen der Suite. Es ist Administratoren vorbehalten und schreibt in die Datei .env.local des Projekts. Über der Maske steht der Zustand: Konfiguriert oder Nicht konfiguriert.

So hinterlegen Sie die SMTP-Zugangsdaten

1. SMTP-Konfiguration als Administrator öffnen.
2. Im Abschnitt Server SMTP-Host, Port und Verschlüsselung eintragen. Zur Wahl stehen Keine, STARTTLS (meist Port 587) und SSL/TLS (meist Port 465).
3. Benutzername und Passwort eintragen. Beim späteren Bearbeiten gilt: „Leer lassen, um das gespeicherte Passwort beizubehalten.“
4. Im Abschnitt E-Mail die Absenderadresse und einen Testempfänger eintragen. „An diese Adresse wird vor dem Speichern eine Test-E-Mail gesendet.“
5. Testen und speichern klicken.
6. Warten und das Browserfenster geöffnet lassen. Der Vorgang läuft synchron ab: Erst wird die Test-E-Mail gesendet, dann werden die Einstellungen geschrieben, dann wird der Cache in einem Unterprozess neu aufgebaut. Das dauert spürbar – der Abbruch dieses Unterprozesses ist auf 120 Sekunden eingestellt.
7. Bei Erfolg erscheint „Test-E-Mail in … s zugestellt. Einstellungen gespeichert, Cache neu aufgebaut.“ Der Zustand oben wechselt auf Konfiguriert.

Vorschau und Testversand

Beide Funktionen liegen als Symbole in der Liste der Nachrichten – Vorschau und Test senden – und stehen jedem Benutzer zur Verfügung, der das Modul Benachrichtigungen öffnen darf.

So prüfen Sie eine Nachricht vor dem Versand

1. In der Nachrichtenliste auf Vorschau klicken.
2. Das Ergebnis wird mit dem aufgelösten Betreff angezeigt, umschaltbar zwischen Desktop und Mobil sowie zwischen HTML und Nur-Text. Der Hinweis „Die Token-Werte sind Beispiele, keine echten Daten.“ steht dabei; hat die Nachricht keinen HTML-Teil, erscheint „Diese Nachricht hat keinen HTML-Teil.“
3. Zurück in die Liste und auf Test senden klicken.
4. Im Formular Testnachricht senden die Tokens der Nachricht ausfüllen. Verwendet die Nachricht keine, steht dort „Diese Nachricht verwendet keine Tokens, die Sie ausfüllen müssen.“
5. Unter Senden an die Zieladresse eintragen. Voreingestellt ist die Adresse Ihres Backend-Kontos.
6. Test senden klicken.
7. Die Bestätigung „Testnachricht an … gesendet. Das Ergebnis steht im Versandprotokoll.“ abwarten und den Eintrag dort prüfen.

Versandprotokoll

Das Modul Versandprotokoll hält jeden Sendeversuch fest. Die Einträge lassen sich ansehen, erneut senden und löschen – aber nicht bearbeiten: Ein Protokoll, das sich ändern lässt, kann nur noch lügen.

So senden Sie eine fehlgeschlagene Nachricht erneut

1. Versandprotokoll öffnen. Die Liste ist nach Datum absteigend sortiert und lässt sich nach Status, Absendertyp, Benachrichtigung und Ausgelöst durch filtern sowie nach Empfängeradresse durchsuchen.
2. Den Eintrag suchen und mit Details anzeigen öffnen, um Fehlertext und gesendeten Inhalt zu sehen.
3. Die Ursache beheben – Absender, Empfängeradresse, Mailserver.
4. In der Liste auf Erneut senden klicken. Die Nachricht wird unverändert erneut gesendet, ohne die Tokens neu aufzulösen.
5. Die Meldung lesen: „Die Nachricht wurde erneut an … gesendet.“ oder „Das erneute Senden ist fehlgeschlagen: …“.

Ist das Symbol Erneut senden inaktiv, lautet der Hinweis: „Dieser Eintrag kann nicht erneut gesendet werden: der Inhalt wurde nicht gespeichert oder der Absender existiert nicht mehr.“ Der häufigste Grund ist ein abgeschaltetes log.store_body.

Zusätzlich versucht die Suite fehlgeschlagene Nachrichten einmal pro Stunde selbst erneut – bis zur konfigurierten Anzahl an Versuchen (log.max_attempts, Voreinstellung 3). Solche Einträge tragen unter Ausgelöst durch den Wert Automatischer Wiederholversuch.

Auslöser im Frontend

Eine Benachrichtigung wird an vier Stellen im Frontend ausgelöst. Wo eine Auswahl möglich ist, trägt das Feld den Namen Benachrichtigungen und liegt im gleichnamigen Abschnitt.

So verknüpfen Sie eine Benachrichtigung

1. Formular: Im Formulargenerator das Formular öffnen und im Abschnitt Benachrichtigungen die gewünschten Einträge auswählen. Jedes übermittelte Feld steht danach als ##feldname## zur Verfügung – maßgeblich ist der „name“ des Feldes, nicht seine Beschriftung. Hochgeladene Dateien werden der Nachricht automatisch angehängt.
2. Mitglieder: Das Frontend-Modul öffnen – Registrierung, Persönliche Daten, Konto schließen, Passwort ändern oder Passwort vergessen – und im Abschnitt Benachrichtigungen auswählen. Angeboten werden nur Benachrichtigungen vom passenden Typ.
3. Newsletter: Ebenso in den Modulen für An- und Abmeldung.
4. Kommentare: Keine Auswahl nötig und keine vorhanden – es genügt, eine Benachrichtigung vom Typ Ein neuer Kommentar anzulegen.

Der Hilfetext am Feld im Formulargenerator lautet: „Die Benachrichtigungen, die beim Absenden dieses Formulars ausgelöst werden. Jedes übermittelte Feld steht im Nachrichtentext als Token ##feldname## zur Verfügung (der „name“ des Feldes im Formulargenerator). Zusätzlich gibt es ##all_fields_html## für eine Tabelle aller Eingaben.“ An den Modulen lautet er: „Die Benachrichtigungen, die bei Verwendung dieses Moduls gesendet werden. Es werden nur zum Modul passende Benachrichtigungen aufgeführt (Mitglieder oder Newsletter).“

Import aus Notification Center

Bestehende Konfigurationen aus terminal42/notification_center lassen sich übernehmen. Der Import ist ein Konsolenbefehl und ausdrücklich keine Migration: Die Benachrichtigungskonfiguration einer Website umzuschreiben ist eine Entscheidung und nichts, was als Nebenwirkung von contao:migrate geschehen sollte.

So führen Sie den Import durch

1. Datensicherung anlegen.
2. Zuerst den Probelauf ausführen:

   vendor/bin/contao-console notification:import-nc --dry-run

3. Die Ausgabe durchsehen. Am Ende listet der Befehl alle Tokennamen auf, die er nicht übersetzen konnte – diese bleiben unverändert stehen und müssen anschließend von Hand geprüft werden.
4. Den Import ausführen:

   vendor/bin/contao-console notification:import-nc

5. Im Backend die angelegten Benachrichtigungen, Nachrichten und Absender durchgehen und je Nachricht eine Vorschau öffnen.
6. Erst danach die alten Auslöser umstellen. Notification Center bleibt unangetastet, beide Installationen können parallel laufen, bis Sie mit dem Ergebnis zufrieden sind.

Gelesen werden die Tabellen tl_nc_notification, tl_nc_message, tl_nc_language und tl_nc_gateway. Da Notification Center eine Ebene tiefer gliedert, wird aus jeder dortigen Sprache-Zeile eine Nachricht dieser Suite, mit dem Absender aus der übergeordneten Zeile. Tokennamen werden dabei übersetzt: ##form_email## wird zu ##email##, ##raw_data## zu ##all_fields## und so fort.

Teil 3 — Für Entwickler

Versand aus eigenem Code

Der Service CentralizedNotificationSuite ist der einzige Einstiegspunkt. Übergeben wird der Alias der Benachrichtigung, die Token-Werte und optional eine Sprache.

use VTInnovations\CentralizedNotificationSuite\CentralizedNotificationSuite;

public function __construct(private readonly CentralizedNotificationSuite $notify) {}

$result = $this->notify->send('bestellbestaetigung', [
    'kunde_name' => $order->name,
    'summe'      => $order->formattedTotal,
], 'de');

$result->isSuccessful();
$result->hasFailures();
$result->countSent();
$result->getStatuses();
$result->getErrors();

Ereignisse

Zwei Symfony-Ereignisse umschließen jede einzelne Zustellung.

Als source erscheint einer der Werte api, form, test, resend oder cron – dieselben Werte, die im Versandprotokoll unter Ausgelöst durch angezeigt werden.

Konsolenbefehle

vendor/bin/contao-console notification:send bestellbestaetigung \
    -t kunde_name=Jane -t email=jane@example.com

vendor/bin/contao-console notification:send bestellbestaetigung \
    --tokens-json='{"kunde_name":"Jane"}' --language=de --dry-run

Erweiterungspunkte

Drei Schnittstellen sind zur Erweiterung vorgesehen. Alle drei werden automatisch registriert: Der Container versieht jede Klasse, die eine davon implementiert, mit dem passenden Tag. Es genügt, die Klasse im eigenen Bundle abzulegen.

Kein Erweiterungspunkt sind die Modelle, die Migrationen und die Backend-Listener dieses Pakets. Sie sind Implementierung und können sich zwischen zwei Versionen ändern, ohne dass das als Bruch gilt.

Tabellen und Hooks

Zusätzlich ergänzt das Paket die Spalte notification_ids auf tl_form und tl_module.

Beim Versionswechsel eines umbenannten Vorgängerpakets laufen zwei Migrationen mit: RenameToNotificationMigration benennt die alten Tabellen um und schreibt dabei die Modulschlüssel in tl_user_group.modules mit, damit eine Nicht-Administrator-Gruppe ihre Freigaben nicht verliert; PruneRenamedCronJobsMigration entfernt verwaiste Zeilen aus tl_cron_job. AssignFormNotificationTypeMigration setzt auf bestehenden Benachrichtigungen den passenden Typ. Alle drei sind wiederholbar ausführbar.

Das genannte Backend-Asset gibt das globale $ an MooTools zurück, wenn eine andere Erweiterung jQuery ohne noConflict() darüber geladen hat. Es wird ausschließlich auf den Bearbeitungsbildschirmen dieses Pakets eingebunden, damit es die Bildschirme anderer Erweiterungen nicht stört.

Routen und Cron-Jobs

Die Vorschau rendert den Nachrichteninhalt in einem abgeschotteten iframe, damit ein <script> aus einem eingefügten Design nicht gegen die Backend-Sitzung laufen kann. Als cid: eingebettete Bilder werden für die Vorschau in data:-URIs überführt – sonst zeigte die Vorschau ein kaputtes Bild für eine Nachricht, die einwandfrei ankommt.

Protokollierung

Betriebsmeldungen gehen in das Contao-Systemprotokoll: Vorgang, Ergebnis und – beim Versand – die betroffene Nachricht. Typische Einträge sind eine Nachricht, die wegen eines fehlenden Absenders übersprungen wurde, und eine fehlgeschlagene Zustellung samt Fehlertext des Transports.

Nicht in den Betriebsmeldungen erscheinen vollständige Lizenzschlüssel und Authentifizierungsdaten. Betreff und Inhalt einer Nachricht speichert das Versandprotokoll nur, wenn log.store_body aktiv ist; auf Installationen ohne Speicherung personenbezogener Daten wird diese Option abgeschaltet – dann entfällt allerdings auch der erneute Versand.

Deployment

composer install --no-dev --optimize-autoloader
vendor/bin/contao-console contao:migrate --no-interaction
vendor/bin/contao-console cache:clear --env=prod
vendor/bin/contao-console cache:warmup --env=prod

Zu beachten:

• Ein privates Verzeichnis unterhalb von var/ muss für den Webserver-Benutzer beschreibbar sein und gehört in die Datensicherung – nicht in die Versionsverwaltung.
• Die Lizenz ist an Hostnamen gebunden. Test-, Staging- und Produktivsystem benötigen jeweils eine für ihren Hostnamen gültige Lizenz.
• Ausgehende HTTPS-Verbindungen dürfen nicht blockiert sein – weder für die Lizenz noch für Webhook-Absender.
• Für den Mailversand muss ein Messenger-Worker laufen oder der Web-Worker von Contao aktiv sein.
• Nach einer Änderung der SMTP-Konfiguration im Backend erneuert die Suite den Cache selbst; nach Änderungen an config/config.yaml geschieht das nicht.

Fehlerbehebung

Bekannte Einschränkungen

• Der Versand setzt eine aktivierte Lizenz voraus. Ohne Lizenz wird nichts zugestellt.
• Eine Lizenz gilt nur für die Hostnamen, für die sie ausgestellt wurde; verwandte Schreibweisen gelten nicht automatisch mit.
• Die Versionierung erfasst die Nachricht selbst, nicht ihre Bausteine. Das Zurückholen einer älteren Nachrichtenversion stellt deren Bausteine nicht wieder her.
• Der Datei-Absender ist für Entwicklung und Prüfung gedacht und stellt nicht zu.
• Für den Webhook-Absender liefert die Suite Vorlagen; das Format des Zielsystems bestimmt der jeweilige Dienst.
• Ob eine E-Mail tatsächlich zugestellt wird, hängt vom Mailserver und vom Betrieb der Messenger-Warteschlange ab. Der Status Zugestellt besagt, dass der Absender die Nachricht abgegeben hat – nicht, dass sie im Posteingang liegt.
• Das Paket erzeugt keine Frontend-Ausgabe.
• Auf Contao 5.3 bis 5.6 werden die Vorschaukarten der Bausteine über eine ältere Contao-Schnittstelle erzeugt, weil diese Versionen noch keine Datensatz-Beschriftung für Eltern-Ansichten kennen. Darstellung, Sortierung per Drag & Drop und alle übrigen Funktionen verhalten sich identisch.

Deinstallation

1. Datensicherung anlegen.
2. Im Backend unter Einstellungen → V-T.ONE Licence management auf der Karte Centralized Notification Suite die Schaltfläche Lizenz entfernen wählen. Es werden keine Inhalte gelöscht.
3. Die Verknüpfungen lösen: im Formulargenerator und in den Mitglieder- und Newsletter-Modulen das Feld Benachrichtigungen leeren. Andernfalls bleibt eine Auswahl stehen, die nach der Deinstallation ins Leere zeigt.
4. Das Paket entfernen – im Contao Manager über den Bereich Pakete, auf der Kommandozeile mit:

   composer remove vtinnovations/centralized-notification-suite

5. Cache leeren:

   vendor/bin/contao-console cache:clear --env=prod

6. Die Tabellen des Pakets bleiben in der Datenbank bestehen, solange Sie sie nicht entfernen. Das ist Absicht: Eine spätere Neuinstallation findet die Konfiguration unverändert vor. Wer sie endgültig loswerden will, löscht die unter Tabellen und Hooks genannten Tabellen von Hand – nach einer Sicherung.
7. Die Laufzeitdaten des Pakets liegen in privaten Verzeichnissen unterhalb von var/ und können nach der Deinstallation entfernt werden; dazu gehört, falls Sie einen Datei-Absender genutzt haben, auch var/notification-mail.