Lernseite · TCA, FlexForms und Datenbankschema

TCA, FlexForms und Datenbankschema: Wie TYPO3 Tabellen beschreibt

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

Fast alles in TYPO3 ist ein Datensatz in einer Tabelle. Damit TYPO3 mit einer Tabelle arbeiten kann, braucht sie eine Beschreibung: das Table Configuration Array, kurz TCA. Auf dieser Seite beschreibst du die Tabellen einer kleinen Extension. Danach weißt du, wie Formulare, Feldtypen, Relationen, Übersetzungen und FlexForms zusammenspielen.

Was das TCA ist

Das TCA ist ein großes PHP-Array. Für jede Tabelle im Backend steht darin, welche Felder es gibt, wie sie im Formular aussehen und wie sie beim Speichern geprüft werden. Die FormEngine baut daraus die Formulare im Backend. Der DataHandler nutzt es beim Speichern. Seit TYPO3 13 leitet TYPO3 daraus auch die meisten Datenbankspalten ab. Die Zugangsdaten zur Datenbank stehen dagegen in der Systemkonfiguration, und die Ausgabe im Frontend macht TypoScript oder Fluid.

Das TCA einer Tabelle hat in TYPO3 14 vier Abschnitte:

  • ctrl beschreibt die Tabelle als Ganzes.
  • columns beschreibt jedes Feld.
  • types legt fest, welche Felder im Formular erscheinen.
  • palettes fasst Felder zu Gruppen zusammen.

Den früheren Abschnitt interface wertet TYPO3 14 nicht mehr aus.

Unser Beispiel: Die Extension my_extension verwaltet Konferenzen. Dazu kommen Vorträge als Kinddatensätze, Schlagwörter, Referenten mit Porträtfoto und Veranstaltungsorte. Ein Plugin zeigt die Konferenzen im Frontend.

Dateien, Cache und Datenbankschema

Jede eigene Tabelle bekommt eine Datei im Ordner Configuration/TCA, benannt nach der Tabelle. Die Datei gibt das Array mit return zurück. Änderungen an fremden Tabellen gehören in den Ordner Configuration/TCA/Overrides, für Seiten also in eine Datei pages.php. Eine Kopie der Core-Datei ersetzt nichts.

Ein neues Feld in den Seiteneigenschaften braucht dort zwei Aufrufe der Klasse ExtensionManagementUtility:

  1. addTCAcolumns() fügt die Felddefinition hinzu. Damit ist das Feld bekannt, erscheint aber noch nirgends.
  2. addToAllTCAtypes() trägt das Feld in die Feldlisten aller Typen ein. Der vierte Parameter bestimmt die Position, zum Beispiel after:title.
1 Basisdateien laden Configuration/TCA/*.php 2 Felder aus ctrl ergänzen hidden, starttime, sys_language_uid … 3 Overrides laden Configuration/TCA/Overrides/*.php 4 Migrationen anwenden Veraltetes wird automatisch umgebaut 5 Fertiges TCA im Cache nach Änderungen Cache leeren Schritt 1: Hier ist das TCA noch unvollständig.
So entsteht das TCA. Am Ende steht alles im Cache.

Beim Laden der Basisdateien ist das TCA noch unvollständig. Seit TYPO3 14 kann eine Basisdatei deshalb nicht mehr in das globale TCA schauen, etwa um Werte von pages zu übernehmen. Solche Zugriffe gehören in die Overrides. Zur Laufzeit liest du das TCA über die Schema API mit ihren TcaSchema-Objekten.

Das fertige TCA liegt im Cache. Erscheint ein neues Feld nicht, auch nicht für Administratoren, gibt es zwei typische Ursachen. Der Cache wurde nicht geleert, oder das Feld fehlt in der Feldliste des Typs.

Datenbankspalten: Seit TYPO3 13 legt TYPO3 die meisten Spalten selbst an. Das gilt für uid und pid und für alles, was in ctrl genannt ist. Dazu gehören deleted, hidden, starttime, endtime, tstamp, crdate, das Sortierfeld, die Sprachfelder und die vier Workspace-Felder. Auch fast alle Feldtypen bekommen ihre Spalte automatisch.

Ein Datumsfeld vom Typ datetime wird ohne weitere Angabe eine BIGINT-Spalte mit Vorzeichen. So passen auch Geburtstage vor 1970 hinein. Mit der Option dbType und dem Wert date entsteht eine echte DATE-Spalte, die leer sein darf.

Selbst definieren musst du nur, wenn du abweichen willst. Was in ext_tables.sql steht, hat immer Vorrang. Für eine fremde Tabelle schreibst du ein unvollständiges CREATE TABLE, und TYPO3 führt es mit der Tabelle zusammen.

CREATE TABLE pages (
    tx_myext_rating int(11) DEFAULT '0' NOT NULL
);
Ein unvollständiges CREATE TABLE für pages mit nur einer Spalte, tx_myext_rating als Ganzzahl.

Anwenden musst du das Schema nach jeder Installation oder Änderung. Im Backend geht das im Modul Maintenance mit „Analyze Database Structure“, bei Deployments mit dem Befehl extension:setup. Cache leeren ändert die Datenbank nicht, und der DataHandler legt nie Spalten an.

Die Tabelle beschreiben

Der ctrl-Abschnitt ist Pflicht. Die wichtigsten Optionen:

  • title ist der Name der ganzen Tabelle, etwa „Konferenz“.
  • label nennt genau ein Feld, das als Titel jedes Datensatzes erscheint.
  • label_alt nennt Ersatzfelder, falls das label-Feld leer ist. Mit label_alt_force hängt TYPO3 sie immer an, getrennt durch Komma. Ein Ort heißt dann „Kongresshalle, Berlin“.
  • iconfile verweist auf eine Bilddatei. TYPO3 macht daraus das Symbol der Datensätze. Die Datei Extension.svg ist dagegen das Symbol der Extension.
  • sortby mit dem Feld sorting lässt Redakteure die Reihenfolge festlegen. Der DataHandler schreibt dort Zahlen hinein. default_sortby sortiert nur fest und wird ignoriert, sobald sortby gesetzt ist.
  • delete markiert gelöschte Datensätze nur.
  • enablecolumns steuert die Sichtbarkeit im Frontend: verbergen, Start- und Endzeit, Frontend-Benutzergruppen.

Wo Datensätze liegen dürfen: rootLevel 0 heißt nur auf Seiten, 1 nur auf der Wurzel mit der pid 0, minus 1 an beiden Stellen. Auf der Wurzel anlegen dürfen trotzdem nur Administratoren, außer du setzt im security-Teil ignoreRootLevelRestriction. Auch der Seitentyp entscheidet mit: Ordner erlauben alle Tabellen, Standardseiten nur wenige. Für Standardseiten setzt du im security-Teil ignorePageTypeRestriction auf true. Die alte Methode allowTableOnStandardPages gibt es nicht mehr.

Neu in TYPO3 14: Die Option searchFields ist entfernt. Felder wie input und text sind automatisch durchsuchbar, einzelne schaltest du mit searchable ab. Außerdem kann jeder Eintrag unter types einen eigenen title haben, sonst gilt der title aus ctrl.

Das Formular

Jedes Feld unter columns hat ein label und eine config mit dem type. Ein Pflichtfeld bekommt in config required mit true. Die alte Schreibweise über eval gehört nicht in neuen Code.

exclude regelt nur Rechte. Redakteure ohne Admin-Rechte sehen das Feld erst, wenn ihre Backend-Gruppe es unter „Allowed fields“ freigibt.

showitem im Abschnitt types legt Felder, Reihenfolge und Tabs fest. Ein Feld, das dort fehlt, erscheint nicht. Paletten zeigen zusammengehörige Felder nebeneinander, etwa Start- und Endzeit.

'types' => ['0' => ['showitem' => 'title, description, --div--;Termine, --palette--;;dates']],
'palettes' => ['dates' => ['showitem' => 'starttime, endtime']],
Die Feldliste zeigt title und description, dann einen Tab Termine mit der Palette dates. Die Palette enthält Start- und Endzeit.

Felder bedingt zeigen: Das Feld external_url soll nur erscheinen, wenn im Feld link_type „external“ gewählt ist. Dafür bekommt external_url eine displayCond mit dem Präfix FIELD. Damit das Formular sofort reagiert, bekommt link_type onChange mit dem Wert reload.

'external_url' => ['displayCond' => 'FIELD:link_type:=:external', /* … */],
'link_type' => ['onChange' => 'reload', /* … */],
external_url bekommt die Bedingung FIELD, link_type, gleich, external. link_type bekommt onChange reload.

Page TSconfig passt das Formular für einen Teilbaum an, ohne das TCA zu ändern. TCEFORM blendet Felder aus, TCAdefaults belegt neue Datensätze vor.

TCEFORM.tx_myext_item.teaser.disabled = 1
TCAdefaults.tx_myext_item.status = 2
Das Feld teaser wird ausgeblendet, neue Datensätze bekommen den Status 2.

Feldtypen für Eingaben

Der type bestimmt Speicherung und Prüfung. Der renderType ändert nur die Darstellung. Der passende Typ bringt Prüfung, Darstellung und die richtige Spalte mit.

  • input ist einzeilig, text mehrzeilig. Mit enableRichtext wird text zum Rich Text Editor, mit dem renderType codeEditor zum Code-Editor.
  • check ist eine Checkbox für Ja oder Nein. Der renderType checkboxToggle zeigt einen Schalter.
  • radio wählt genau einen von mehreren Werten.
  • number hat das format integer oder decimal mit zwei Nachkommastellen, etwa für Preise.
  • email, link mit Link-Browser und color mit Farbwähler prüfen und zeigen ihre Werte passend.
  • json speichert JSON und zeigt einen Code-Editor.
  • password speichert gehasht, denn hashed ist standardmäßig true.
  • datetime kennt die Formate date, datetime, time, timesec und, neu in TYPO3 14, datetimesec.
  • uuid erzeugt eine technische Kennung, country ist neu in TYPO3 14.

Typen wie integer, date, boolean oder textarea gibt es nicht.

Grenzen: Eine Bewertung hat range mit lower 1 und upper 5. Kommt beim Speichern der Wert 7, speichert der DataHandler still 5. Willst du einen Fehler, prüfst du vorher selbst, etwa mit einem Validator.

fieldControl sind Schaltflächen am Feld. Beim Typ group sind das zum Beispiel addRecord, editPopup, listModule, elementBrowser und insertClipboard.

Relationen, Dateien und Ordner

Typ Wofür, und wo es landet select Auswahl aus einer Tabelle uid-Liste oder MM-Tabelle group eine oder mehrere Tabellen tabellenname_uid inline Kinder im Elternformular Kind hält Eltern-uid category Systemkategorien als Baum sys_category_record_mm file Dateien und Bilder sys_file_reference
Fünf Wege, Datensätze zu verknüpfen.

select bietet mit foreign_table die Datensätze einer Tabelle an. Mit foreign_table_where hängst du eine Bedingung an. Platzhalter wie CURRENT_PID ersetzt das Backend vor der Abfrage, hier durch die pid des bearbeiteten Datensatzes.

'foreign_table_where' => 'AND {#tx_myext_category}.{#pid} = ###CURRENT_PID###',
Nur Kategorien aus demselben Ordner. Die pid der Kategorie wird mit dem Platzhalter CURRENT_PID verglichen.

Die renderTypes von select sind selectSingle, selectSingleBox, selectCheckBox, selectTree und selectMultipleSideBySide. Der letzte zeigt zwei Listen nebeneinander und passt für lange Listen mit Mehrfachauswahl. Radiobuttons sind dagegen der eigene Typ radio. Seit TYPO3 14 passen itemsProcessors die Auswahlwerte an. Sie erfüllen das ItemsProcessorInterface, geben eine SelectItemCollection zurück und ersetzen itemsProcFunc.

MM: Konferenzen bekommen mehrere Schlagwörter über ein select-Feld mit MM-Tabelle. Diese Tabelle legt TYPO3 selbst an, mit uid_local, uid_foreign und den Sortierspalten. Das Feld zählt dann nur die Schlagwörter. Ohne MM steht dort eine kommagetrennte Liste. Soll die Relation auch von der Gegenseite bearbeitbar sein, braucht diese MM_opposite_field.

group kann über die Option allowed auf mehrere Tabellen zeigen, etwa auf Seiten und Inhaltselemente. Gespeichert wird Tabellenname und uid.

inline bearbeitet Kinddatensätze direkt im Elternformular, etwa die Vorträge. foreign_table nennt die Kindtabelle, foreign_field die Spalte im Kind, die auf die Konferenz zeigt.

category ist der einfachste Weg zu den Systemkategorien. Bei relationship manyToMany, dem Standard, liegen die Verknüpfungen in sys_category_record_mm. Bei oneToOne speichert das Feld genau eine uid. Die Kombination oneToMany mit maxitems 1 lehnt TYPO3 mit einer Exception ab.

file kopiert keine Dateien. Jede Verknüpfung ist ein Datensatz in sys_file_reference, der auf sys_file zeigt. Die Option allowed mit common-image-types erlaubt nur Bilder. Für genau ein Porträtfoto setzt du relationship auf manyToOne. Dann liefert das Record-Objekt direkt eine Dateireferenz statt einer Liste.

folder speichert die kombinierte Kennung aus Speicher und Pfad, etwa die Eins, einen Doppelpunkt und den Ordnerpfad. Ordner haben keine Datensätze.

Slugs, eigene Felder und Datensatztypen

Ein Slug ist der lesbare Teil des URL-Pfads. Schema und Domain gehören nie dazu. Für Konferenzen braucht es zusätzlich einen Route Enhancer in der Site-Konfiguration. Slugs sind immer klein geschrieben, unerlaubte Zeichen ersetzt der fallbackCharacter. Die generatorOptions steuern den Vorschlag:

  • fields nennt die Quellfelder. Ein inneres Array heißt: das erste nicht leere Feld. Einträge oben werden mit dem fieldSeparator verbunden.
  • regexReplacements ist neu in TYPO3 14 und ersetzt Teile per regulärem Ausdruck.
  • prefixParentPageSlug wirkt nur bei Seiten. Dort ist auch der führende Schrägstrich fest eingeschaltet.
'fields' => [['nav_title', 'title'], 'subtitle'],
// nav_title leer, title "Produkte", subtitle "Neu"  =>  produkte/neu
Erst nav_title, und wenn er leer ist, title, danach subtitle. Bei leerem nav_title, dem Titel Produkte und dem Untertitel Neu entsteht produkte, Schrägstrich, neu.

Die Eindeutigkeit legt eval fest. Ist ein Slug vergeben, hängt TYPO3 eine Zahl an. unique prüft die ganze Tabelle je Sprache und ist empfohlen. uniqueInSite prüft je Site. Dann lassen sich Datensätze fremder Sites aber nicht anzeigen. uniqueInPid prüft nur im selben Ordner.

Typ user: Er speichert den Wert ohne Prüfung. Anders als none braucht er eine Datenbankspalte. Ohne eigenen renderType zeigt die FormEngine nur einen Platzhalter. Die alte Option userFunc gibt es nicht mehr. Einen renderType meldest du in der Systemkonfiguration unter SYS, formEngine, nodeRegistry an. Hängst du ihn an einen bestehenden Typ wie input, bleibt die Verarbeitung samt Prüfungen erhalten. Das ist besser, wenn nur die Darstellung anders sein soll.

Single Table Inheritance: Verschiedene Arten von Datensätzen liegen in einer Tabelle. Die Option type in ctrl nennt das Feld, das die Art bestimmt, etwa CType bei Inhalten oder doktype bei Seiten. Unter types bekommt jede Art eine eigene Feldliste, mit columnsOverrides passt du einzelne Felder an. Die zweite Ebene über subtype_value_field gibt es nicht mehr. Neue Typen brauchen keine neue Tabelle und keine Joins. Dafür teilen sich alle Typen alle Spalten.

Übersetzungen und Workspaces

Übersetzbar wird eine Tabelle über ctrl, die Felder legt TYPO3 an:

  • languageField zeigt auf sys_language_uid. Null ist die Standardsprache, minus 1 heißt „alle Sprachen“.
  • transOrigPointerField zeigt auf l10n_parent, das Original.
  • transOrigDiffSourceField zeigt auf l10n_diffsource für den Vergleich.

Einzelne Felder: l10n_mode exclude blendet das Feld in Übersetzungen aus und hält den Wert synchron. prefixLangTitle kopiert den Wert und stellt den Sprachtitel voran. Die alten Werte mergeIfNotBlank und noCopy gibt es nicht mehr. l10n_display defaultAsReadonly zeigt den Wert der Standardsprache schreibgeschützt. Mit allowLanguageSynchronization entscheidet der Redakteur je Übersetzung, ob ein Feld synchron bleibt. Der Zustand steht in l10n_state.

DataHandler-Befehle: localize verknüpft die Übersetzung über l10n_parent mit dem Original, das ist der verbundene Modus. copyToLanguage erzeugt eine freie Kopie ohne diesen Bezug.

Eigene Abfragen: Die Restrictions des QueryBuilders filtern keine Sprachen. Für Übersetzungen rufst du für jede Zeile getLanguageOverlay() des PageRepository auf. Die LocalizationUtility übersetzt nur Texte aus XLIFF-Dateien.

Workspaces zeigen Änderungen erst nach dem Veröffentlichen live, vorher in einer Vorschau. Sie brauchen die System-Extension workspaces. Eine eigene Tabelle wird workspace-fähig mit versioningWS. TYPO3 legt dann die vier Felder an, die mit t3ver beginnen. Versionen sind eigene Zeilen derselben Tabelle. In einem eigenen Query wählt die WorkspaceRestriction die Zeilen aus. Danach mischt versionOL() die Workspace-Werte ein.

FlexForms

Redakteure sollen pro Plugin festlegen, wie viele Konferenzen erscheinen. Dafür ist eine FlexForm da. Ihre Werte liegen als XML in einer einzigen Spalte, bei Plugins in pi_flexform. Site-Settings oder TypoScript-Konstanten gelten dagegen für ganze Bereiche, nicht pro Element.

Die Felder nutzen dieselben config-Optionen wie TCA-Spalten. Per SQL kann man die Werte aber nicht filtern oder sortieren. Standardwerte kommen aus default, TCAdefaults wirkt hier nicht.

Aufbau: Unter sheets steht je Reiter ein Sheet mit ROOT, die Felder stehen in el. displayCond und onChange funktionieren auch hier. Das alte TCEforms-Element muss raus, sonst wird die FlexForm fehlerhaft angezeigt.

<T3DataStructure>
  <sheets><sDEF><ROOT><type>array</type><el>
    <settings.limit>
      <label>my_extension.flexform:limit</label>
      <config><type>number</type><default>10</default></config>
    </settings.limit>
  </el></ROOT></sDEF></sheets>
</T3DataStructure>
Eine FlexForm mit dem Sheet sDEF und dem Feld settings.limit vom Typ number.

Anmelden: Seit TYPO3 14 übergibst du die FlexForm als siebten Parameter von ExtensionUtility::registerPlugin(). Ein Dateipfad braucht das Präfix FILE mit Doppelpunkt. Die alte Methode addPiFlexFormValue ist veraltet, ds_pointerField ist entfernt.

FlexForm-Datei ConferenceList.xml: settings.limit Redakteur füllt aus Eine Spalte voller XML tt_content.pi_flexform drei Lesewege Extbase settings['limit'] / {settings.limit} PHP: FlexFormTools convertFlexFormContentToArray() TypoScript flexform:pi_flexform:settings.limit Nicht per SQL filterbar oder sortierbar. Standardwert aus default, nicht TCAdefaults.
Eine Spalte voller XML, drei Wege zum Wert.

Auslesen: In Extbase landen Felder mit dem Präfix settings automatisch in den settings des Controllers, settings.limit also unter dem Schlüssel limit. Nicht leere Werte überschreiben TypoScript. In einem Konsolenbefehl liefert convertFlexFormContentToArray() von FlexFormTools ein einfaches Array. Die Klasse FlexFormService ist darin aufgegangen und nur noch ein Alias. In TypoScript nutzt du die Funktion flexform mit Feld und Name.

data = flexform:pi_flexform:settings.categories
data liest mit flexform aus pi_flexform den Wert settings.categories.

Ändern bei Upgrades: Lies das XML mit GeneralUtility::xml2array() ein, ändere das Array und schreibe es mit flexArray2Xml() von FlexFormTools zurück.

Das Wichtigste in Kürze

  • Das TCA hat vier Abschnitte: ctrl, columns, types und palettes.
  • Eigene Tabellen stehen in Configuration/TCA, Änderungen an fremden in den Overrides.
  • Viele Spalten entstehen automatisch, ext_tables.sql hat Vorrang.
  • Ein Feld erscheint nur, wenn es in showitem steht.
  • Der type bestimmt die Verarbeitung, der renderType nur die Darstellung.
  • Dateien laufen über sys_file_reference, Kinddatensätze über inline.
  • FlexForms speichern XML in einer Spalte und werden bei registerPlugin angegeben.

Begriffe

FormEngine
Baut die Backend-Formulare aus dem TCA.
DataHandler
Speichert Datensätze nach den Regeln des TCA.
Palette
Gruppe von Feldern, die nebeneinander stehen.
renderType
Darstellungsvariante eines Feldtyps.
MM-Tabelle
Zwischentabelle für Relationen mit mehreren Partnern auf beiden Seiten.
Slug
Lesbarer Teil des URL-Pfads.
FlexForm
Formular, dessen Werte als XML in einer Spalte liegen.

Stand: 15. November 2026 (TYPO3 14.3 LTS)

Quellen:

  • TCA Reference 14.3 (docs.typo3.org/m/typo3/reference-tca/main/en-us/), Kapitel Ctrl, Columns, Types, Palettes
  • TYPO3 Explained 14.3, Kapitel Database (Schema, ext_tables.sql), FlexForms, Workspaces und Frontend Localization
  • Quellcode TYPO3 14.3 (typo3/cms-core), geprüft für DataHandler, SlugHelper, TcaPreparation, DefaultTcaSchema und FlexFormTools
  • Changelog TYPO3 14.0 bis 14.3
  • Lernzielkatalog TYPO3 CMS Certified Developer 14 LTS, Bereich Daten, TCA und Persistenz

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