Lernseite · Extbase: MVC, Plugins und Views

Extbase verstehen: Vom Request bis zur fertigen Ausgabe

Stand 15. November 2026 · TYPO3 14.3 LTS · ca. 15 Min. Lesezeit

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.php ist der Controller.
  • Classes/Domain/Model/Conference.php ist das Modell, Classes/Domain/Repository/ enthält die Repositories.
  • Resources/Private/Templates/, Layouts/ und Partials/ enthalten die Fluid-Dateien, Resources/Private/Language/ die Übersetzungen.
  • ext_localconf.php und Configuration/TCA/Overrides/tt_content.php melden 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.

TYPO3 Extbase TYPO3 1 Browser ruft die URL auf /konferenzen/ 2 TYPO3 findet die Seite Seitenrouter, Seitenbaum 3 Inhalte rendern: Plugin gefunden CType myextension_conferencelist 4 Bootstrap liest die Konfiguration Extbase übernimmt 5 Dispatcher wählt den Controller ConferenceController 6 Argumente prüfen, Action aufrufen showAction(Conference $c) 7 View rendert, Response zurück return $this->htmlResponse(); 8 HTML an der Stelle des Plugins zwischen den anderen Inhalten
Ein Request durch Extbase. Die Schritte 4 bis 7 erledigt Extbase, den Rest TYPO3.

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]=42
Beispiel-URL, in der die Action show und die Konferenz Nummer 42 im Namensraum tx_myextension_conferencelist stehen.

Schö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();
}
Codebeispiel. Die listAction holt alle Konferenzen aus dem Repository, gibt sie mit assign an die View und endet mit 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 mit withHeader() eigene Header hinzu.
  • Nach dem Speichern zeigt addFlashMessage() eine Meldung an. Im Template gibt <f:flashMessages /> sie aus. Die Stufe wählst du mit ContextualFeedbackSeverity, etwa WARNING. Den Text holst du mit LocalizationUtility::translate('flash.saved', 'MyExtension') aus der locallang.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 Browser Server POST create 303 See Other 2. Request, neue URL GET show HTML Forward Browser Server POST create Forward new HTML 2 Requests · URL neu 1 Request · URL bleibt
Redirect geht über den Browser, Forward bleibt im selben Request.
  • 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:

  1. ExtensionUtility::configurePlugin() in ext_localconf.php verbindet 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.
  2. ExtensionUtility::registerPlugin() in Configuration/TCA/Overrides/tt_content.php macht 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'],
);
Codebeispiel für configurePlugin. Das Plugin ConferenceList erlaubt list, show, new und create. new und create stehen zusätzlich im vierten Parameter und werden deshalb nicht gecacht.

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.

Request ruft eine Action auf Steht die Action im 4. Parameter von configurePlugin()? Nein Ja USER Ausgabe kommt in den Seitencache USER_INT bei jedem Aufruf neu gerendert Redirects und Fehler (Status ab 300) werden nie gecacht.
Entschieden wird je Action, nicht je Plugin.

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
}
TypoScript-Beispiel. lib.conferenceList wird ein EXTBASEPLUGIN mit extensionName MyExtension und 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:

  1. Sie fügt eine Fehlermeldung hinzu, deren Text aus getErrorFlashMessage() kommt.
  2. Sie gibt per Forward an die Action zurück, die das Formular gezeigt hat.
  3. 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 Action und geben immer ein ResponseInterface zurü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 arguments gibst.
  • Ein Plugin braucht configurePlugin() und registerPlugin() mit identischen Namen und ist seit v14 ein eigener CType.
  • 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.

Stand: 15. November 2026 (TYPO3 14.3 LTS)

Quellen:

  • TYPO3 Explained 14.3, Kapitel Extbase (docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/Extbase/)
  • TypoScript-Referenz 14.3, EXTBASEPLUGIN und USER/USER_INT
  • Quellcode TYPO3 14.3 (typo3/cms-extbase), geprüft für die Abschnitte zu errorAction, Redirect und Caching
  • Lernzielkatalog TYPO3 CMS Certified Developer 14 LTS, Bereich Extbase

Diese Lernseite ist mit KI erstellt und gegen die Quellen geprüft.

Zertifikate & Prüfungen

Welche Prüfung kommt als Nächstes?

51 Prüfungen kannst du schon üben, über 16 stimmst du gerade ab. Sieh dir alle Zertifikate mit offiziellen Infos an, gib deine Stimme ab oder schlag deine Prüfung vor.

Zur Zertifikatsübersicht