Lernseite · Extbase: MVC, Plugins und Views
Extbase verstehen: Vom Request bis zur fertigen Ausgabe
Extbase ist das Werkzeug in TYPO3, mit dem du Extensions mit eigenem Datenmodell baust, etwa für Veranstaltungen, Produkte oder Stellenanzeigen. Auf dieser Seite folgst du einer einzigen Anfrage durch Extbase: von der URL über Controller und View bis zum fertigen HTML. Unterwegs lernst du, wie man Plugins anmeldet, wie das Caching entscheidet und was passiert, wenn etwas schiefgeht.
Was ist Extbase?
Extbase ist ein Framework im TYPO3-Core. Es teilt den Code nach dem Muster Model-View-Controller, kurz MVC:
- Das Model beschreibt deine Daten, zum Beispiel eine Konferenz mit Titel und Datum.
- Der Controller nimmt die Anfrage entgegen und entscheidet, was passiert.
- Die View macht aus den Daten eine Ausgabe, meistens HTML.
Dazu bringt Extbase einen Object-Relational Mapper mit. Du arbeitest also mit PHP-Objekten statt mit SQL. Die Template-Engine heißt Fluid. Extbase nutzt Fluid als View, Fluid ist aber ein eigenes Paket und nicht Extbase selbst.
Das Beispiel auf dieser Seite
Alle Beispiele gehören zu einer Extension mit dem Key my_extension. Sie hat ein Modell Conference, einen ConferenceController mit den Actions list, show, new und create und ein Plugin ConferenceList. Die Dateien liegen an festen Orten:
Classes/Controller/ConferenceController.phpist der Controller.Classes/Domain/Model/Conference.phpist das Modell,Classes/Domain/Repository/enthält die Repositories.Resources/Private/Templates/,Layouts/undPartials/enthalten die Fluid-Dateien,Resources/Private/Language/die Übersetzungen.ext_localconf.phpundConfiguration/TCA/Overrides/tt_content.phpmelden das Plugin an.
Das Modell Conference erweitert AbstractEntity und wird über seine uid erkannt. Wertobjekte ohne eigene Identität schreibst du seit TYPO3 14 als einfache PHP-Klassen, denn AbstractValueObject ist dort nur noch intern. Wie Modelle gespeichert und geladen werden, behandelt der Kurs „Extbase: Persistenz und Validierung“.
Der Weg eines Requests
Extbase bekommt nicht die ganze URL wie ein eigenständiges Framework. Zuerst sucht TYPO3 die passende Seite im Seitenbaum. Erst wenn TYPO3 die Inhaltselemente dieser Seite ausgibt und dabei auf ein Plugin trifft, übernimmt Extbase. Ein Plugin ist also eine kleine Anwendung innerhalb einer Seite. Deshalb können mehrere Plugins auf derselben Seite stehen.
Damit sich Plugins nicht in die Quere kommen, haben ihre URL-Argumente einen eigenen Namensraum. Er lautet tx_ plus Extension-Key ohne Unterstriche plus Plugin-Name, alles klein. Für unser Plugin heißt das:
?tx_myextension_conferencelist[action]=show&tx_myextension_conferencelist[conference]=42Schöne URLs ohne diese Klammern entstehen erst durch einen Route Enhancer in der Site-Konfiguration. Extbase selbst baut keine schönen URLs.
Sollen zwei Plugins dieselben Argumente lesen, etwa ein Filter und eine Liste, gibst du beiden mit view.pluginNamespace denselben Namensraum.
Controller und Actions
Ein Controller erweitert ActionController. Jede öffentliche Methode, deren Name auf Action endet, ist eine Action. Aus action=list wird also der Aufruf von listAction(). Eine Methode list() ohne Endung ruft Extbase nie als Action auf.
Jede Action muss ein ResponseInterface zurückgeben. Meist ist das $this->htmlResponse(). Ohne Argument rendert es das Template, das zur Action gehört.
public function listAction(): ResponseInterface
{
$this->view->assign('conferences', $this->conferenceRepository->findAll());
return $this->htmlResponse();
}Vor der Action ruft Extbase vorbereitende Methoden auf, und zwar in dieser Reihenfolge: initializeAction() für alle Actions, dann initializeShowAction() nur vor showAction(), dann das Umwandeln der Argumente, dann initializeView(), dann die Action selbst. In initializeCreateAction() stellt man zum Beispiel ein, in welchem Format ein Datum aus dem Formular ankommt.
Argumente bekommt die Action über ihre Parameter. Für showAction(Conference $conference) lädt Extbase das Objekt mit der UID aus der URL selbst. Optionale Parameter brauchen einen Standardwert, etwa int $currentPage = 1. Alternativ fragst du den Request direkt: $this->request->hasArgument('currentPage') und getArgument('currentPage').
Weitere Daten findest du an zwei Stellen. $this->request ist ein PSR-7-Request. Daraus liest du Attribute wie den angemeldeten Frontend-Benutzer mit getAttribute('frontend.user'). Controller- und Action-Name stecken im Attribut extbase. $this->settings enthält die Einstellungen aus TypoScript und FlexForm. Die Werte aus TypoScript sind dort Strings: itemsPerPage = 10 kommt als '10' an.
Antworten, Redirect und Forward
Nicht jede Action liefert eine HTML-Seite:
$this->jsonResponse()gibt JSON aus, entweder über die JsonView oder mit einem fertigen JSON-String als Argument.$this->htmlResponse()->withStatus(404)rendert das Template, sendet aber den Status 404. Genauso fügst du mitwithHeader()eigene Header hinzu.- Nach dem Speichern zeigt
addFlashMessage()eine Meldung an. Im Template gibt<f:flashMessages />sie aus. Die Stufe wählst du mitContextualFeedbackSeverity, etwaWARNING. Den Text holst du mitLocalizationUtility::translate('flash.saved', 'MyExtension')aus derlocallang.xlf. - Eine absolute URL, etwa für eine Bestätigungs-E-Mail, baut
$this->uriBuilder->reset()->setCreateAbsoluteUri(true)->uriFor('show', ['conference' => $conference]).
Nach einem Formular will man meistens zu einer anderen Action wechseln. Dafür gibt es zwei Wege, die sich deutlich unterscheiden.
- Redirect:
return $this->redirect('show', null, null, ['conference' => $conference]);schickt dem Browser den Status 303. Der Browser lädt dann die neue Seite. Lädt jemand diese Seite neu, wird das Formular nicht noch einmal abgeschickt, und es entsteht kein doppelter Datensatz. - Forward:
return new ForwardResponse('new');gibt die Arbeit im selben Request an eine andere Action weiter. Die URL bleibt gleich, und eine andere Zielseite kannst du damit nicht angeben.
Die View: Fluid
Der Controller übergibt Daten mit $this->view->assign('conferences', $conferences) oder mehrere auf einmal mit assignMultiple([...]). Im Template stehen sie dann als {conferences} bereit, Einstellungen als {settings.itemsPerPage}.
Welches Template? Extbase leitet den Dateinamen aus Controller und Action ab. Für ConferenceController::showAction() ist das Resources/Private/Templates/Conference/Show.fluid.html. Die Endung .fluid.html ist seit TYPO3 14 üblich, alte .html-Dateien funktionieren weiter. Bei einem anderen Format wie JSON sucht Fluid nach Show.fluid.json.
Templates überschreiben: Die Pfade stehen in drei Listen, templateRootPaths, layoutRootPaths und partialRootPaths. Jeder Eintrag hat eine Zahl als Schlüssel. Der höchste Schlüssel wird zuerst durchsucht. Der Standardpfad der Extension hat die niedrigste Priorität.
Layouts und Partials: Ein Layout ist der Rahmen um das Template. Es holt mit <f:render section="Main" /> den Abschnitt, den das Template mit <f:section name="Main"> liefert. Ein Partial ist ein wiederverwendbares Stück, etwa eine Karte für eine Konferenz. Es sieht nur die Variablen, die du ihm gibst: <f:render partial="ConferenceItem" arguments="{conference: conference}" />. Mit arguments="{_all}" gibst du alles weiter.
Wenn {conference.title} leer bleibt: Fluid sucht eine öffentliche Eigenschaft oder einen Getter wie getTitle(). Findet es nichts, gibt es still einen leeren Text aus, ohne Fehlermeldung. Typische Ursachen sind ein Tippfehler im Variablennamen, ein fehlender Getter oder ein Partial ohne arguments.
CSS und JavaScript: Die Sections HeaderAssets und FooterAssets sind seit TYPO3 14 veraltet und fallen mit v15 weg. Nimm stattdessen <f:page.headerData> und <f:page.footerData>.
Links und Formulare: <f:link.action action="show" arguments="{conference: conference}"> verlinkt auf eine Action. Liegt die Detailansicht auf einer anderen Seite in einem anderen Plugin, ergänzt du pageUid und pluginName. Ein Formular für createAction(Conference $newConference) beginnt mit <f:form action="create" name="newConference" object="{newConference}">, die Felder verbindest du mit property="title".
JSON statt HTML: Setzt ein Controller protected ?string $defaultViewObjectName = JsonView::class;, liefern alle seine Actions JSON. Mit setVariablesToRender() wählst du die Variablen aus. Ohne diesen Aufruf gibt die JsonView nur die Variable value aus. Eine eigene View-Klasse, die keine JsonView ist, lehnt Extbase an dieser Stelle mit einer RuntimeException ab. Mit setConfiguration() und den Schlüsseln _only, _exclude, _descend und _descendAll bestimmst du, welche Eigenschaften im JSON landen.
Plugins anmelden
Ein Extbase-Plugin braucht zwei Aufrufe mit genau demselben Extension- und Plugin-Namen:
ExtensionUtility::configurePlugin()inext_localconf.phpverbindet das Plugin mit Controllern und Actions. Die erste Action des ersten Controllers ist die Standard-Action. Der vierte Parameter nennt die Actions, die nicht gecacht werden dürfen.ExtensionUtility::registerPlugin()inConfiguration/TCA/Overrides/tt_content.phpmacht das Plugin im Backend auswählbar, mit Titel, Icon, Gruppe, Beschreibung und FlexForm.
ExtensionUtility::configurePlugin(
'MyExtension',
'ConferenceList',
[ConferenceController::class => 'list, show, new, create'],
[ConferenceController::class => 'new, create'],
);Seit TYPO3 14 ist jedes Plugin ein eigenes Inhaltselement mit eigenem CType. Das alte „Allgemeine Plugin“ mit list_type gibt es nicht mehr. Der CType heißt wie die Plugin-Signatur: Extension-Name ohne Unterstriche, Unterstrich, Plugin-Name, alles klein, höchstens 32 Zeichen. Bei uns also myextension_conferencelist. Eine FlexForm übergibst du an registerPlugin() als Pfad mit dem Präfix FILE:.
Woher kommen die Einstellungen? Extbase fügt die Konfiguration in dieser Reihenfolge zusammen, spätere Quellen gewinnen: config.tx_extbase, dann plugin.tx_myextension für alle Plugins der Extension, dann plugin.tx_myextension_conferencelist für dieses Plugin, zuletzt die FlexForm. Ein leeres FlexForm-Feld überschreibt dabei den Wert aus TypoScript. Trägst du das Feld in ignoreFlexFormSettingsIfEmpty ein, bleibt der TypoScript-Wert erhalten.
Ohne Extbase geht ein Plugin auch: Eine PHP-Methode wird per TypoScript als USER (gecacht) oder USER_INT (ungecacht) mit userFunc aufgerufen. Seit TYPO3 14 braucht diese Methode das Attribut #[AsAllowedCallable]. Als Inhaltselement meldest du sie mit ExtensionManagementUtility::addPlugin() an.
Caching: gecacht oder nicht?
Normalerweise landet die Ausgabe eines Plugins im Seitencache. Der nächste Besucher bekommt sie fertig, ohne dass dein Controller noch einmal läuft. Das ist schnell, passt aber nicht für alles.
Nicht cachebar sollte eine Action nur sein, wenn ihre Ausgabe nicht geteilt werden darf: Formulare mit frischem Sicherheits-Token, Inhalte je angemeldetem Benutzer oder Live-Daten. Eine Action muss dafür im dritten und im vierten Parameter stehen.
EXTBASEPLUGIN: Mit diesem TypoScript-Objekt gibst du ein Extbase-Plugin auch ohne Inhaltselement aus, zum Beispiel einen Warenkorb im Seitenkopf jeder Seite. configurePlugin() erzeugt selbst genau so ein Objekt für das Inhaltselement.
lib.conferenceList = EXTBASEPLUGIN
lib.conferenceList {
extensionName = MyExtension
pluginName = ConferenceList
}Für das Caching gilt dieselbe Regel: Das Objekt startet als gecachtes USER. Ist die aufgerufene Action nicht cachebar, wird es zu USER_INT. Antworten mit einem Status ab 300, etwa Redirects, werden nie im Cache abgelegt.
Wenn etwas schiefgeht
Ungültige Formulardaten: Schlägt das Umwandeln oder Prüfen der Argumente fehl, ruft Extbase statt der Action die eingebaute errorAction() auf. Sie macht drei Dinge:
- Sie fügt eine Fehlermeldung hinzu, deren Text aus
getErrorFlashMessage()kommt. - Sie gibt per Forward an die Action zurück, die das Formular gezeigt hat.
- Sie setzt den Status 400.
Seit TYPO3 14 legt die errorAction() diese Meldung nicht mehr in der Session ab. Sonst hätten Crawler massenhaft unnötige Sessions erzeugt. Willst du gar keine Meldung, überschreibst du getErrorFlashMessage() und gibst false zurück. Für volle Kontrolle überschreibst du errorAction() selbst.
Datensatz nicht gefunden: Ruft jemand showAction() mit der UID eines gelöschten Datensatzes auf, wirft Extbase eine TargetNotFoundException. Die errorAction() greift hier nicht. Mit mvc.showPageNotFoundIfTargetNotFoundException = 1 zeigt TYPO3 stattdessen die 404-Seite. Brauchst du etwas anderes, etwa einen Log-Eintrag und eine Weiterleitung, überschreibst du handleArgumentMappingExceptions() im Controller.
Das Wichtigste in Kürze
- Extbase übernimmt erst, wenn TYPO3 auf der Seite ein Plugin rendert.
- Actions enden auf
Actionund geben immer einResponseInterfacezurück. - Redirect: Status 303, neuer Request über den Browser. Forward: gleicher Request, gleiche URL.
- Templates liegen unter
Templates/<Controller>/<Action>.fluid.html, der höchste Pfad-Schlüssel wird zuerst durchsucht. - Partials sehen nur, was du ihnen mit
argumentsgibst. - Ein Plugin braucht
configurePlugin()undregisterPlugin()mit identischen Namen und ist seit v14 ein eigenerCType. - Ob gecacht wird, entscheidet die aufgerufene Action: vierter Parameter =
USER_INT. errorAction()gilt für ungültige Argumente, nicht für fehlende Datensätze.
Begriffe
- Action
- Öffentliche Controller-Methode mit der Endung „Action“.
- Dispatcher
- Wählt den Controller und ruft ihn auf, verarbeitet auch Forwards.
- Flash-Message
- Kurze Meldung, die nach einer Aktion einmal angezeigt wird.
- Namensraum
- Präfix der URL-Argumente eines Plugins, z. B. tx_myextension_conferencelist.
- Plugin-Signatur
- Extension-Name ohne Unterstriche plus Plugin-Name, klein, ergibt den CType.
- PSR-7
- PHP-Standard für Request- und Response-Objekte.
- USER / USER_INT
- Gecachtes bzw. ungecachtes TypoScript-Objekt.