Lernseite · CLI, Scheduler, Message Bus und Mail
Arbeit im Hintergrund: Kommandozeile, Scheduler, Message Bus, Mail und Upgrades
Viel Arbeit in TYPO3 passiert, ohne dass jemand eine Seite aufruft. Unser Beispiel ist wieder die Extension my_extension. Sie importiert nachts Vorträge, erzeugt nach jeder Anmeldung im Hintergrund eine PDF und verschickt sie per Mail. In Version 2 bringt sie einen Upgrade Wizard mit.
Die Kommandozeile von TYPO3
Die Kommandozeile von TYPO3 baut auf Symfony Console auf. Die Befehle heißen deshalb nach dem Muster Bereich, Doppelpunkt, Aktion, etwa cache:flush. In einer Composer-Installation rufst du das Skript typo3 im Ordner vendor, Unterordner bin, auf.
vendor/bin/typo3 list
vendor/bin/typo3 help cache:flush
vendor/bin/typo3 extension:setup
vendor/bin/typo3 upgrade:run- Der Befehl
listzeigt alle Befehle aus Core und Extensions, gruppiert nach Präfix. - Der Befehl
helpmit einem Befehlsnamen dahinter zeigt dessen Argumente und Optionen. - Der Befehl
extension:setuplegt nach dem Installieren oder Aktualisieren von Extensions neue Tabellen und Felder an. Er gehört in jedes Deployment. - Der Befehl
upgrade:runführt Upgrade Wizards aus,upgrade:listzeigt die offenen.
Die Kommandozeile braucht keinen angemeldeten Backend-Benutzer und läuft in jedem Application Context, auch in Production.
Ein eigener Befehl
Ein eigener Befehl erweitert die Klasse Command von Symfony Console. Angemeldet wird er mit dem Symfony-Attribut AsCommand, das Namen und Beschreibung nennt. Alternativ trägst du ihn in der Services.yaml mit dem Tag console.command ein.
#[AsCommand(name: 'myextension:import-talks', description: 'Importiert Vorträge')]
final class ImportTalksCommand extends Command
{
public function __construct(private readonly TalkImporter $importer)
{
parent::__construct();
}
protected function configure(): void
{
$this->addArgument('conference', InputArgument::REQUIRED)
->addOption('dry-run', null, InputOption::VALUE_NONE);
}
protected function execute(InputInterface $input, OutputInterface $output): int
{
$io = new SymfonyStyle($input, $output);
$count = $this->importer->import((int)$input->getArgument('conference'));
$io->success($count . ' Vorträge importiert');
return Command::SUCCESS;
}
}Argumente und Optionen beschreibst du in configure() mit addArgument() und addOption(). Argumente stehen beim Aufruf an ihrer Position, Optionen bekommen zwei Bindestriche vor den Namen. Fehlt ein Pflichtargument, bricht die Console ab, bevor execute() läuft. Gelesen werden die Werte mit getArgument() und getOption().
Ausgabe: execute() bekommt ein InputInterface und ein OutputInterface. Ausgaben laufen über den Output, nicht über echo. Bequemer ist SymfonyStyle mit farbigen Erfolgsmeldungen, Tabellen, Fortschrittsbalken und Rückfragen.
Ausführlichkeit: Die Schalter für mehr Ausgabe, also ein bis drei kleine v, wertet Symfony selbst aus. Du fragst sie am Output mit isVerbose(), isVeryVerbose() oder isDebug() ab. Sie sind keine Optionen deines Befehls.
Rückgabe: execute() gibt einen ganzzahligen Exit-Code zurück. Command::SUCCESS ist 0, Command::FAILURE ist 1, Command::INVALID ist 2. Daran erkennen Skripte und Cron das Ergebnis.
Dienste kommen per Dependency Injection über den Konstruktor. Dann musst du parent::__construct() aufrufen. Sonst bricht Symfony mit der Meldung ab, die Command-Klasse sei nicht richtig initialisiert.
Kontext: Auf der Kommandozeile gibt es keinen Request, keine Site, kein TypoScript und keinen angemeldeten Benutzer. Brauchst du Seitenlinks, etwa in einer Fluid-Mail, musst du einen Request selbst erzeugen.
Der Scheduler
Der Scheduler führt Aufgaben zeitgesteuert aus. Seit TYPO3 14 findest du ihn in der Modulgruppe Administration, nur für Administratoren. Denn TYPO3 14 hat umbenannt: Die alte Gruppe System heißt jetzt Administration, die alte Gruppe Admin Tools heißt jetzt System.
Der Scheduler startet nichts von selbst. Ein Cronjob ruft regelmäßig den Befehl scheduler:run auf, zum Beispiel alle fünf Minuten. Dann startet der Scheduler alle fälligen Tasks. Seitenaufrufe oder Backend-Anmeldungen starten keine Tasks.
Wann läuft ein Task? Er ist einmalig, zu einem festen Zeitpunkt, oder wiederkehrend. Wiederkehrende Tasks bekommen ein Intervall in Sekunden, etwa 3600 für stündlich, oder einen Cron-Ausdruck, etwa für täglich um drei Uhr. Ein Enddatum kann die Laufzeit begrenzen.
Parallele Läufe sind standardmäßig nicht erlaubt. Läuft ein Task alle fünf Minuten, braucht aber acht, überspringt der Scheduler den nächsten Start.
Priorität: Seit TYPO3 14.2 hat jeder Task die Priorität hoch, normal oder niedrig. Sie entscheidet vor dem Zeitpunkt der nächsten Ausführung über die Reihenfolge.
Befehle als Tasks und eigene Tasks
Jeder Befehl ist planbar. Im neuen Task-Assistenten von TYPO3 14 erscheint jeder Konsolenbefehl als eigener Task-Typ, gruppiert nach dem Präfix vor dem Doppelpunkt. cache:flush steht also in der Gruppe cache. Argumente und Optionen füllst du im Formular des Tasks aus. So wird unser Import ein nächtlicher Task, ohne Scheduler-Code.
Soll ein Befehl nicht planbar sein, setzt du seit TYPO3 14 das Attribut AsNonSchedulableCommand an die Klasse. Früher brauchte man dafür in der Services.yaml den Eintrag schedulable mit dem Wert false.
Ein eigener Task ohne Befehl lohnt sich, wenn du eigene Formularfelder brauchst:
- Die Klasse erweitert
AbstractTask. Ihre Methodeexecute()gibt true bei Erfolg zurück. - In den TCA-Overrides der Tabelle
tx_scheduler_taskmeldest du sie mit der Methode addRecordType derExtensionManagementUtilityals eigenen Typ an. - Eigene Felder sind normale TCA-Spalten. Der Task liest und schreibt sie mit
getTaskParameters()undsetTaskParameters().
Seit TYPO3 14 ist jeder Task ein TCA-Datensatz mit den Feldern tasktype und parameters, statt eines serialisierten PHP-Objekts. Ein Upgrade Wizard stellt alte Tasks um. Auch die Häufigkeits-Optionen kommen jetzt aus dem TCA. Die Anmeldung über die SC_OPTIONS mit einem AdditionalFieldProvider ist veraltet.
Task oder Befehl? Einen Befehl startest du direkt auf der Kommandozeile und zusätzlich im Scheduler. Ein klassischer Task läuft nur im Scheduler und speichert seine Einstellungen im Task-Datensatz. Startet Cron den Scheduler, laufen beide im CLI-Kontext ohne Frontend-Request. Startet ein Administrator einen Task von Hand im Modul, läuft er dagegen im Backend-Request dieses Benutzers. Für neue Aufgaben ist ein Befehl meist flexibler.
Synchron oder asynchron
Synchron heißt: Die Aufgabe wird sofort erledigt, der Aufrufer wartet. Langsame Aufgaben verlängern so die Antwortzeit.
Asynchron heißt: Die Aufgabe kommt als Nachricht in eine Warteschlange. Ein eigener Prozess, der Worker, erledigt sie später. Der Aufrufer wartet nicht auf das Ergebnis.
Asynchron passt für lange Arbeiten, deren Ergebnis niemand sofort braucht: einen großen PDF-Export, Mailversand, Bildverarbeitung oder Aufrufe fremder Schnittstellen. Login, Seitenausgabe und die Prüfung eines Pflichtfelds brauchen ihr Ergebnis dagegen sofort.
Vorteile: Langsame oder fehleranfällige Aufrufe blockieren den Request nicht. Lastspitzen und Ausfälle fremder Dienste werden entkoppelt, das System wird robuster.
Herausforderungen:
- Ein Worker muss dauerhaft laufen oder regelmäßig starten.
- Fehler treten nicht mehr in der ursprünglichen Anfrage auf und müssen getrennt überwacht werden.
- Nachrichten können mehrfach ankommen. Handler sollten deshalb idempotent sein, also mehrfach ausführbar ohne Schaden.
- Das Ergebnis fehlt dem aktuellen Request, und schneller wird die Aufgabe auch nicht.
Der Message Bus
Der Message Bus von TYPO3 baut auf Symfony Messenger auf.
Die Nachricht ist eine beliebige, einfache PHP-Klasse ohne Basisklasse. Gesendet wird sie über das MessageBusInterface von Symfony, das du per Dependency Injection holst. Der Absender kennt den Handler nicht. Der Handler trägt das Symfony-Attribut AsMessageHandler und bekommt die Nachricht als Parameter.
final readonly class CreateCertificateMessage
{
public function __construct(public int $registrationUid) {}
}
// im Controller
$this->bus->dispatch(new CreateCertificateMessage($registration->getUid()));
#[AsMessageHandler]
final class CreateCertificateHandler
{
public function __invoke(CreateCertificateMessage $message): void
{
// Anmeldung laden, PDF erzeugen, Mail senden
}
}Alternativ meldest du den Handler in der Services.yaml an. Dort legst du mit before und after auch die Reihenfolge mehrerer Handler fest.
Standard ist synchron. Ohne weitere Einstellung leitet TYPO3 alle Nachrichten an den synchronen Transport default. Er verarbeitet sie sofort im selben Request. Fehlt der Handler, wirft TYPO3 eine Exception.
Asynchron wird es erst mit einer Route auf einen asynchronen Transport. Der Transport doctrine speichert Nachrichten in einer Tabelle der TYPO3-Datenbank. Die Route schreibst du in die Datei additional.php im Ordner config, Unterordner system.
$GLOBALS['TYPO3_CONF_VARS']['SYS']['messenger']['routing'][CreateCertificateMessage::class] = 'doctrine';
// oder für alle Nachrichten:
$GLOBALS['TYPO3_CONF_VARS']['SYS']['messenger']['routing']['*'] = 'doctrine';Der Worker arbeitet die Warteschlange ab. Ohne ihn bleiben asynchrone Nachrichten liegen.
vendor/bin/typo3 messenger:consume doctrine --time-limit=3600Seit TYPO3 14.2 kennt der Befehl die Grenzen von Symfony für Zeit, Anzahl, Fehler und Speicher. Mit einer Grenze beendet sich der Worker regelmäßig und gibt Speicher frei. Ein Dienst-Manager wie systemd startet ihn dann neu.
E-Mails verschicken
Die Mail API baut Nachrichten mit Symfony Mime und verschickt sie mit Symfony Mailer.
Einstellungen gelten für die ganze Installation. Sie stehen im Bereich MAIL der TYPO3_CONF_VARS, einstellbar im Modul Settings der Gruppe System. Für verschiedene Umgebungen setzt du sie in der additional.php je Application Context.
- Transport: Voreingestellt ist sendmail. Mit smtp schickst du über einen bestimmten Mailserver, etwa mit
transport_smtp_server. Der Transport mbox schreibt alle Mails in die Datei austransport_mbox_file, praktisch für Entwicklungsrechner. Möglich sind auch eine eigene Klasse, die dasTransportInterfacevon Symfony umsetzt, oder eine DSN. - Absender:
defaultMailFromAddressunddefaultMailFromNamegelten, wenn eine Extension keinen Absender setzt. - Spool: Mit dem Spool-Typ memory gehen Mails erst am Ende des Requests raus. Mit file sammelt TYPO3 sie in einem Ordner, und der Befehl
mailer:spool:sendverschickt sie regelmäßig. So wartet kein Besucher nach dem Absenden eines Formulars auf den Mailserver.
Testen: Im Modul Environment der Gruppe System verschickt „Test Mail Setup“ eine Testmail über den eingestellten Transport.
Bauen und senden: MailMessage ist in TYPO3 14 ein reines Datenobjekt. Wie FluidEmail erweitert es die Klasse Email von Symfony Mime. Den Inhalt setzt du mit Methoden wie text() und html(). Versendet wird immer über das MailerInterface von TYPO3, das du per Konstruktor bekommst. Die alte Methode send an der Mail selbst ist in TYPO3 14 entfernt.
$email = (new FluidEmail())
->from(new Address('team@example.org', 'Konferenz-Team'))
->to(new Address($attendee->getEmail(), $attendee->getName()))
->subject('Ihre Anmeldung')
->setTemplate('RegistrationConfirmation')
->assign('attendee', $attendee)
->format(FluidEmail::FORMAT_HTML)
->setRequest($request);
$email->attachFromPath($pdfPath, 'Teilnahmebestaetigung.pdf');
$this->mailer->send($email);- Adressen beschreibt die Klasse
Address: erst die Adresse, dann der Anzeigename. Ein einfacher Text mit der Adresse geht auch, dann ohne Namen. - Anhänge:
attachFromPath()hängt eine Datei an, optional mit Namen und Typ.attach()nimmt Inhalte aus dem Speicher. - FluidEmail sucht ihr Template in den Pfaden der Einstellung templateRootPaths im Bereich MAIL. Deinen Pfad ergänzt du dort mit einem höheren Schlüssel, etwa 700. Schlüssel unter 100 sind für den Core reserviert.
- Format:
format()wählt nur HTML, nur Text oder beides. Beides ist Standard. - Links im Template brauchen den Request aus
setRequest(). Seit TYPO3 14.2 erzeugt dieTemplatedEmailFactoryFluidEmails zentral.
Eingreifen: Vor dem Versand löst der Mailer das BeforeMailerSentMessageEvent aus. Ein Listener holt die Nachricht mit getMessage() und ändert sie. So bekommt auf einem Testsystem jede Mail eine Blindkopie ans Team, egal welche Extension sie schickt. Eine Einstellung dafür gibt es nicht. Nach dem Versand folgt das AfterMailerSentMessageEvent, etwa zum Protokollieren.
Upgrades und Upgrade Wizards
Ein Major-Upgrade, etwa von TYPO3 13 auf 14, probierst du zuerst auf einer Kopie des Live-Systems aus. Vorher sicherst du Datenbank und Dateien.
Warum Deprecations zuerst? TYPO3 markiert API in einer Version als veraltet und entfernt sie in der nächsten Major-Version. Das Deprecation-Log zeigt die betroffenen Aufrufe. In deiner Extension gehst du nach Semantic Versioning genauso vor. Soll eine öffentliche Methode einer neuen weichen, ergänzt du die neue in einer Minor-Version. Die alte markierst du als deprecated und löst beim Aufruf eine Deprecation-Meldung aus. Entfernen darfst du sie erst in der nächsten Major-Version, denn das ist ein Breaking Change.
Upgrade Wizards passen nach einem Update die Daten an. Der Datenbankvergleich ändert nur Tabellen und Spalten, nicht ihren Inhalt. Ein Wizard passt, wenn bestehende Datensätze nach einer Änderung von Feldern oder Werten angepasst werden müssen. Ein Beispiel ist das Umstellen alter Plugins von list_type auf einen eigenen CType mit der Basisklasse AbstractListTypeToCTypeUpdate. Für Arbeit bei jedem Request oder Massenbearbeitung durch Redakteure passt er nicht, denn er läuft einmalig beim Update.
Seit TYPO3 14 liegen Interface und Attribut im Core, die alten Orte in der Extension install sind veraltet.
#[UpgradeWizard('myExtension_moveVenueToLocation')]
final class MoveVenueToLocationWizard implements UpgradeWizardInterface
{
public function getTitle(): string { return 'Ort aus venue nach location übernehmen'; }
public function getDescription(): string { return '…'; }
public function updateNecessary(): bool { /* gibt es noch alte Zeilen? */ }
public function executeUpdate(): bool { /* umschreiben */ return true; }
public function getPrerequisites(): array { return [DatabaseUpdatedPrerequisite::class]; }
}- Die Kennung kommt aus dem Attribut, nicht aus einer Methode.
updateNecessary()prüft, ob es noch etwas zu tun gibt. Sagt sie nein, wird der Wizard nicht angeboten.executeUpdate()migriert und gibt true oder false zurück, keine Anzahl.getPrerequisites()nennt Voraussetzungen. MitDatabaseUpdatedPrerequisitewird zuerst das Datenbankschema aktualisiert.- Mit
RepeatableInterfacegilt der Wizard nie als erledigt und bleibt wählbar.ConfirmableInterfacefragt vorher nach,ChattyInterfaceerlaubt zusätzliche Ausgaben.
Auf der Kommandozeile startest du Wizards mit upgrade:run. Ein Zurücknehmen ist nicht vorgesehen, nur der Befehl upgrade:mark:undone setzt den Status zurück.
Extension Scanner, Rector und Fractor
Der Extension Scanner steckt im Modul Upgrade der Gruppe System, unter „Scan Extension Files“. Er sucht im PHP-Code von Extensions nach Stellen, die laut Changelog entfernt oder veraltet sind, und verlinkt den Eintrag. Er arbeitet mit statischer Codeanalyse und führt nichts aus. Falsche und übersehene Treffer sind deshalb möglich.
- Strong heißt: Der Treffer ist eindeutig, etwa ein bekannter Klassenname.
- Weak heißt: Der Code könnte betroffen sein, etwa weil nur der Methodenname passt. Diesen Fund prüfst du von Hand. Aufrufe über Variablen ergeben fast immer schwache Treffer.
- Versionsweichen im Code erkennt der Scanner nicht.
- Ein grünes Ergebnis garantiert nicht, dass die Extension läuft.
Jeder Changelog-Eintrag trägt eines der Schlagworte FullyScanned, PartiallyScanned oder NotScanned. Daran siehst du, ob der Scanner die Änderung findet. Bei NotScanned prüfst du selbst.
// @extensionScannerIgnoreLine
$foo->someFalsePositiveMatch('foo');Rector schreibt PHP-Code nach Regeln um, TYPO3 Rector bringt sie für jede TYPO3-Version mit. Fractor macht dasselbe für TypoScript, FlexForms, Fluid und andere Dateien, die kein PHP sind. PHPStan analysiert nur, PHP-CS-Fixer formatiert nur.
Der Befehl process mit der Option dry-run zeigt die Änderungen von Rector nur als Diff und schreibt nichts. Lass Rector und Fractor regelmäßig laufen. Dann baust du Deprecations früh ab, das Upgrade wird kleiner, und jede Änderung bleibt im Review überschaubar. Tests und Changelogs ersetzen sie aber nicht.
Benachrichtigungen mit Aktionen
Notifications sind kurze Meldungen oben rechts im Backend. Du erzeugst sie in JavaScript mit dem Notification-Modul des Backends, etwa mit der Methode success. Sie können Aktionen bekommen, also Buttons:
- Die ImmediateAction führt eine einfache Aufgabe sofort aus und schließt die Meldung.
- Die DeferredAction ist für längere Aufgaben wie eine AJAX-Anfrage. Ihr Callback gibt ein Promise zurück, bis dahin zeigt der Button einen Ladekreis. Schließt man die Meldung, läuft die Aufgabe trotzdem weiter.
import Notification from '@typo3/backend/notification.js';
import ImmediateAction from '@typo3/backend/action-button/immediate-action.js';
Notification.success('Import fertig', '42 Vorträge importiert', 0, [
{ label: 'Protokoll öffnen', action: new ImmediateAction(() => { /* Modul öffnen */ }) },
]);Das Wichtigste in Kürze
- Eigene Befehle erweitern
Command, tragenAsCommandund geben einen Exit-Code zurück. - Der Scheduler läuft nur, wenn Cron
scheduler:runaufruft. Parallele Läufe sind standardmäßig aus. - Jeder Befehl ist als Task-Typ planbar, außer mit
AsNonSchedulableCommand. - Der Message Bus nutzt Symfony Messenger und arbeitet standardmäßig synchron. Asynchron braucht Route und Worker.
- Mails versendet das
MailerInterface, voreingestellt ist sendmail. - Upgrade Wizards migrieren Daten, der Extension Scanner findet veraltete PHP-Aufrufe, Rector und Fractor bauen Code um.
Begriffe
- Exit-Code
- Ganze Zahl, mit der ein Befehl Erfolg oder Fehler meldet.
- Handler
- Klasse, die eine Nachricht des Message Bus verarbeitet.
- Idempotent
- Mehrfach ausführbar mit demselben Ergebnis.
- Spool
- Zwischenspeicher für Mails, die später verschickt werden.
- Upgrade Wizard
- PHP-Klasse, die Daten nach einem Update einmalig anpasst.
- Worker
- Prozess, der eine Warteschlange abarbeitet.