Study guide · TCA, FlexForms and Database Schema

TCA, FlexForms and database schema: How TYPO3 describes tables

As of November 15, 2026 · TYPO3 14.3 LTS · about 19 min read

Almost everything in TYPO3 is a record in a table. For TYPO3 to work with a table, the table needs a description: the Table Configuration Array, TCA for short. On this page you describe the tables of a small extension. Afterwards you know how forms, field types, relations, translations and FlexForms work together.

What the TCA is

The TCA is a large PHP array. For every table in the backend it says which fields exist, how they look in the form and how they are checked on save. The FormEngine builds the backend forms from it. The DataHandler uses it when saving. Since TYPO3 13, TYPO3 also derives most database columns from it. The database credentials, on the other hand, live in the system configuration, and frontend output is the job of TypoScript or Fluid.

In TYPO3 14 the TCA of a table has four sections:

  • ctrl describes the table as a whole.
  • columns describes each field.
  • types defines which fields appear in the form.
  • palettes groups fields together.

TYPO3 14 no longer evaluates the former interface section.

Our example: The extension my_extension manages conferences. On top of that there are sessions as child records, tags, speakers with a portrait photo, and venues. A plugin shows the conferences in the frontend.

Files, cache and database schema

Every custom table gets a file in the folder Configuration/TCA, named after the table. The file returns the array with return. Changes to foreign tables belong in the folder Configuration/TCA/Overrides, so for pages in a file called pages.php. A copy of the Core file replaces nothing.

A new field in the page properties needs two calls of the class ExtensionManagementUtility there:

  1. addTCAcolumns() adds the field definition. Now the field is known, but it does not appear anywhere yet.
  2. addToAllTCAtypes() adds the field to the field lists of all types. The fourth parameter sets the position, for example after:title.
1 Load base files Configuration/TCA/*.php 2 Add fields named in ctrl hidden, starttime, sys_language_uid … 3 Load overrides Configuration/TCA/Overrides/*.php 4 Apply migrations outdated settings are rewritten 5 Final TCA in the cache flush caches after changes Step 1: The TCA is still incomplete here.
How the TCA is built. At the end everything sits in the cache.

While the base files are loading, the TCA is still incomplete. That is why, since TYPO3 14, a base file can no longer look into the global TCA, for example to copy values from pages. Such access belongs in the overrides. At runtime you read the TCA through the Schema API and its TcaSchema objects.

The complete TCA sits in the cache. If a new field does not show up, not even for administrators, there are two typical causes. Either the cache was not flushed, or the field is missing from the field list of the type.

Database columns: Since TYPO3 13, TYPO3 creates most columns by itself. That applies to uid and pid and to everything named in ctrl. This includes deleted, hidden, starttime, endtime, tstamp, crdate, the sorting field, the language fields and the four workspace fields. Almost all field types get their column automatically, too.

A date field of type datetime becomes a signed BIGINT column without further settings. That way even birthdays before 1970 fit. With the option dbType set to date you get a real DATE column, which may be empty.

Defining columns yourself is only needed when you want something different. Whatever is in ext_tables.sql always wins. For a foreign table you write an incomplete CREATE TABLE, and TYPO3 merges it with the table.

CREATE TABLE pages (
    tx_myext_rating int(11) DEFAULT '0' NOT NULL
);
An incomplete CREATE TABLE for pages with just one column, tx_myext_rating as an integer.

Applying the schema is necessary after every installation or change. In the backend you do this in the Maintenance module with “Analyze Database Structure”, in deployments with the command extension:setup. Flushing caches does not change the database, and the DataHandler never creates columns.

Describing the table

The ctrl section is mandatory. The most important options:

  • title is the name of the whole table, such as “Conference”.
  • label names exactly one field that is shown as the title of each record.
  • label_alt names fallback fields in case the label field is empty. With label_alt_force TYPO3 always appends them, separated by a comma. A venue is then shown as “Congress Hall, Berlin”.
  • iconfile points to an image file. TYPO3 turns it into the icon of the records. The file Extension.svg, on the other hand, is the icon of the extension.
  • sortby with the field sorting lets editors set the order. The DataHandler writes numbers into it. default_sortby only sets a fixed sorting and is ignored as soon as sortby is set.
  • delete only marks deleted records.
  • enablecolumns controls visibility in the frontend: hiding, start and end time, and frontend user groups.

Where records may live: rootLevel 0 means only on pages, 1 only on the root with pid 0, and minus 1 in both places. Even so, only administrators may create records on the root, unless you set ignoreRootLevelRestriction in the security part. The page type has a say too: folders allow all tables, standard pages only a few. For standard pages you set ignorePageTypeRestriction to true in the security part. The old method allowTableOnStandardPages no longer exists.

New in TYPO3 14: The option searchFields has been removed. Fields such as input and text are searchable automatically, and you switch off single fields with searchable. In addition, each entry under types can have its own title. Otherwise the title from ctrl applies.

The form

Every field under columns has a label and a config with the type. A required field gets required set to true in its config. The old notation through eval does not belong in new code.

exclude only controls permissions. Editors without admin rights only see the field once their backend group allows it under “Allowed fields”.

showitem in the types section defines fields, order and tabs. A field that is missing there does not appear. Palettes show related fields side by side, such as start and end time.

'types' => ['0' => ['showitem' => 'title, description, --div--;Dates, --palette--;;dates']],
'palettes' => ['dates' => ['showitem' => 'starttime, endtime']],
The field list shows title and description, then a tab called Dates with the palette dates. The palette contains start and end time.

Showing fields conditionally: The field external_url should only appear when “external” is selected in the field link_type. For this, external_url gets a displayCond with the prefix FIELD. So that the form reacts right away, link_type gets onChange with the value reload.

'external_url' => ['displayCond' => 'FIELD:link_type:=:external', /* … */],
'link_type' => ['onChange' => 'reload', /* … */],
external_url gets the condition FIELD, link_type, equals, external. link_type gets onChange reload.

Page TSconfig adjusts the form for a subtree without changing the TCA. TCEFORM hides fields, and TCAdefaults sets defaults for new records.

TCEFORM.tx_myext_item.teaser.disabled = 1
TCAdefaults.tx_myext_item.status = 2
The field teaser is hidden, and new records get the status 2.

Field types for input

The type decides storage and validation. The renderType only changes the rendering. The matching type brings validation, rendering and the right column.

  • input is single-line, text is multi-line. With enableRichtext, text becomes the rich text editor, and with the renderType codeEditor a code editor.
  • check is a checkbox for yes or no. The renderType checkboxToggle shows a switch.
  • radio picks exactly one of several values.
  • number has the format integer or decimal with two decimal places, for example for prices.
  • email, link with the link browser and color with a colour picker validate and show their values appropriately.
  • json stores JSON and shows a code editor.
  • password stores the value hashed, because hashed is true by default.
  • datetime knows the formats date, datetime, time, timesec and, new in TYPO3 14, datetimesec.
  • uuid creates a technical identifier, and country is new in TYPO3 14.

Types such as integer, date, boolean or textarea do not exist.

Limits: A rating has range with lower 1 and upper 5. If the value 7 comes in on save, the DataHandler silently stores 5. If you want an error, you check the value yourself beforehand, for example with a validator.

fieldControl elements are buttons next to the field. For the type group these are, for example, addRecord, editPopup, listModule, elementBrowser and insertClipboard.

Relations, files and folders

Type What for, and where it is stored select pick from one table uid list or MM table group one or more tables tablename_uid inline children in parent form child holds parent uid category system categories as tree sys_category_record_mm file files and images sys_file_reference
Five ways to connect records.

select offers the records of one table through foreign_table. With foreign_table_where you append a condition. The backend replaces placeholders such as CURRENT_PID before the query, here with the pid of the record being edited.

'foreign_table_where' => 'AND {#tx_myext_category}.{#pid} = ###CURRENT_PID###',
Only categories from the same folder. The pid of the category is compared with the placeholder CURRENT_PID.

The renderTypes of select are selectSingle, selectSingleBox, selectCheckBox, selectTree and selectMultipleSideBySide. The last one shows two lists side by side and fits long lists with multiple selection. Radio buttons, by contrast, are the separate type radio. Since TYPO3 14, itemsProcessors adjust the items. They implement the ItemsProcessorInterface, return a SelectItemCollection and replace itemsProcFunc.

MM: Conferences get several tags through a select field with an MM table. TYPO3 creates this table itself, with uid_local, uid_foreign and the sorting columns. The field then only counts the tags. Without MM it holds a comma-separated list. If the relation should also be editable from the opposite side, that side needs MM_opposite_field.

group can point to several tables through the option allowed, for example to pages and content elements. It stores the table name and the uid.

inline edits child records directly in the parent form, for example the sessions. foreign_table names the child table, and foreign_field names the column in the child that points to the conference.

category is the simplest way to the system categories. With relationship manyToMany, the default, the connections live in sys_category_record_mm. With oneToOne the field stores exactly one uid. The combination of oneToMany with maxitems 1 is rejected by TYPO3 with an exception.

file does not copy files. Each connection is a record in sys_file_reference that points to sys_file. The option allowed with common-image-types only allows images. For exactly one portrait photo you set relationship to manyToOne. Then the record object returns a file reference directly instead of a list.

folder stores the combined identifier of storage and path, for example the number one, a colon and the folder path. Folders have no records.

Slugs, custom fields and record types

A slug is the readable part of the URL path. Scheme and domain are never part of it. Conferences also need a route enhancer in the site configuration. Slugs are always lowercase, and the fallbackCharacter replaces characters that are not allowed. The generatorOptions control the suggestion:

  • fields names the source fields. An inner array means: the first field that is not empty. Top-level entries are joined with the fieldSeparator.
  • regexReplacements is new in TYPO3 14 and replaces parts with a regular expression.
  • prefixParentPageSlug only works for pages. There the leading slash is always switched on, too.
'fields' => [['nav_title', 'title'], 'subtitle'],
// nav_title empty, title "Products", subtitle "New"  =>  products/new
First nav_title, and if it is empty, title, then subtitle. With an empty nav_title, the title Products and the subtitle New, the result is products, slash, new.

The option eval defines uniqueness. If a slug is taken, TYPO3 appends a number. unique checks the whole table per language and is recommended. uniqueInSite checks per site. But then records from foreign sites cannot be displayed. uniqueInPid only checks within the same folder.

Type user: It stores the value without any checks. Unlike none, it needs a database column. Without a custom renderType the FormEngine only shows a placeholder. The old option userFunc no longer exists. You register a renderType in the system configuration under SYS, formEngine, nodeRegistry. If you attach it to an existing type such as input, the processing and its checks stay in place. That is better when only the rendering should differ.

Single table inheritance: Different kinds of records live in one table. The option type in ctrl names the field that decides the kind, such as CType for content or doktype for pages. Under types each kind gets its own field list, and with columnsOverrides you adjust single fields. The second level through subtype_value_field no longer exists. New types need no new table and no joins. In return, all types share all columns.

Translations and workspaces

A table becomes translatable through ctrl, and TYPO3 creates the fields:

  • languageField points to sys_language_uid. Zero is the default language, and minus 1 means “all languages”.
  • transOrigPointerField points to l10n_parent, the original.
  • transOrigDiffSourceField points to l10n_diffsource for comparison.

Single fields: l10n_mode exclude hides the field in translations and keeps the value in sync. prefixLangTitle copies the value and puts the language title in front. The old values mergeIfNotBlank and noCopy no longer exist. l10n_display defaultAsReadonly shows the value of the default language as read only. With allowLanguageSynchronization the editor decides per translation whether a field stays in sync. The state is stored in l10n_state.

DataHandler commands: localize links the translation to the original through l10n_parent, which is the connected mode. copyToLanguage creates a free copy without this link.

Custom queries: The restrictions of the QueryBuilder do not filter languages. For translations you call getLanguageOverlay() of the PageRepository for each row. The LocalizationUtility only translates labels from XLIFF files.

Workspaces only show changes live after publishing, and in a preview before that. They need the system extension workspaces. A custom table becomes workspace-aware with versioningWS. TYPO3 then creates the four fields that start with t3ver. Versions are separate rows of the same table. In a custom query the WorkspaceRestriction selects the rows. Then versionOL() merges in the workspace values.

FlexForms

Editors should set per plugin how many conferences appear. A FlexForm is meant for this. Its values are stored as XML in one single column, for plugins in pi_flexform. Site settings or TypoScript constants, by contrast, apply to whole areas, not per element.

The fields use the same config options as TCA columns. But you cannot filter or sort the values with SQL. Default values come from default, and TCAdefaults has no effect here.

Structure: Under sheets there is one sheet per tab with ROOT, and the fields sit inside el. displayCond and onChange work here too. The old TCEforms element has to go, otherwise the FlexForm is displayed incorrectly.

<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>
A FlexForm with the sheet sDEF and the field settings.limit of type number.

Registering: Since TYPO3 14 you pass the FlexForm as the seventh parameter of ExtensionUtility::registerPlugin(). A file path needs the prefix FILE with a colon. The old method addPiFlexFormValue is deprecated, and ds_pointerField has been removed.

FlexForm file ConferenceList.xml: settings.limit editor fills in One column full of XML tt_content.pi_flexform three ways to read Extbase settings['limit'] / {settings.limit} PHP: FlexFormTools convertFlexFormContentToArray() TypoScript flexform:pi_flexform:settings.limit Cannot be filtered or sorted via SQL. Defaults come from default, not TCAdefaults.
One column full of XML, three ways to the value.

Reading: In Extbase, fields with the prefix settings end up in the controller's settings automatically, so settings.limit sits under the key limit. Values that are not empty override TypoScript. In a console command, convertFlexFormContentToArray() of FlexFormTools returns a simple array. The class FlexFormService has been merged into it and is only an alias now. In TypoScript you use the function flexform with field and name.

data = flexform:pi_flexform:settings.categories
data uses flexform to read the value settings.categories from pi_flexform.

Changing values in upgrades: Read the XML with GeneralUtility::xml2array(), change the array and write it back with flexArray2Xml() of FlexFormTools.

Key points

  • The TCA has four sections: ctrl, columns, types and palettes.
  • Custom tables live in Configuration/TCA, changes to foreign tables in the overrides.
  • Many columns are created automatically, and ext_tables.sql wins.
  • A field only appears if it is listed in showitem.
  • The type decides the processing, the renderType only the rendering.
  • Files go through sys_file_reference, child records through inline.
  • FlexForms store XML in one column and are passed to registerPlugin.

Terms

FormEngine
Builds the backend forms from the TCA.
DataHandler
Saves records according to the rules of the TCA.
Palette
Group of fields that sit side by side.
renderType
Rendering variant of a field type.
MM table
Intermediate table for relations with several partners on both sides.
Slug
Readable part of the URL path.
FlexForm
Form whose values are stored as XML in one column.

As of: November 15, 2026 (TYPO3 14.3 LTS)

Sources:

  • TCA Reference 14.3 (docs.typo3.org/m/typo3/reference-tca/main/en-us/), chapters Ctrl, Columns, Types, Palettes
  • TYPO3 Explained 14.3, chapters Database (schema, ext_tables.sql), FlexForms, Workspaces and Frontend Localization
  • Source code TYPO3 14.3 (typo3/cms-core), checked for DataHandler, SlugHelper, TcaPreparation, DefaultTcaSchema and FlexFormTools
  • Changelog TYPO3 14.0 to 14.3
  • Learning objectives TYPO3 CMS Certified Developer 14 LTS, area Data, TCA and persistence

This study guide was written with AI and checked against the sources.

Certifications & exams

Which exam comes next?

You can already practise for 51 exams, and 16 are up for a vote. See all certifications with their official information, cast your vote or suggest your exam.

See all certifications