About this document

This document describes the global array called $GLOBALS['TCA'] . This array is a layer on top of the database tables that TYPO3 can operate on. It is a very central element of the TYPO3 architecture.

Almost all code examples used in this manual come either from the TYPO3 source code itself, from the extension examples, or from extension styleguide. Extension styleguide comes with a huge list of TCA examples and field combinations. Installing it locally in some test environment is a good idea since the extension is great as a "show-off" on what can be done with TCA. Even experienced developers will find things they did not know before.

What is $GLOBALS['TCA']?

The Table Configuration Array (or $GLOBALS['TCA'], TCA) is a global array in TYPO3 which extends the definition of database tables beyond what can be done strictly with SQL. First and foremost $GLOBALS['TCA'] defines which tables are editable in the TYPO3 backend. Database tables with no corresponding entry in $GLOBALS['TCA'] are "invisible" to the TYPO3 backend. The $GLOBALS['TCA'] definition of a table also covers the following:

• Relations between that table and other tables
• What fields should be displayed in the backend and with which layout
• How should a field be validated (e.g. required, integer, etc.)
• How a field is used in the frontend by Extbase and any extension that may refer to this information

TCA can be seen as the glue between the DataHandler which takes care of persisting data into the database, and the FormEngine which renders table rows in the Backend. TCA tells both of these main core constructs how they should behave for specific tables, fields and relations. Additionally, some parts of the Frontend rendering process also utilize TCA information, for instance the extbase MVC relies on it.

This array is highly extendable using extensions. Extensions can add fields to existing tables and add new tables. Several required extensions that are always loaded, already deliver some TCA files in their Configuration/TCA directories.

Most importantly, the extension "core" comes with a definition of pages, be_users and further tables needed by the whole system. The extension "frontend" comes with the tables tt_content, fe_users, sys_template and more. See the directories typo3/sysext/core/Configuration/TCA/ and typo3/sysext/frontend/Configuration/TCA/ for the complete list of the TYPO3 CMS tables.

The TCA definition of a new table with the name "database-table-name" must be done in the extension directory Configuration/TCA/ with database-table-name.php as filename. An example is EXT:sys_note/Configuration/TCA/sys_note.php for table "sys_note". This file will be found by the bootstrap code (if starting a TYPO3 request). It must return an array with the content of the TCA setting or NULL if the table should not be defined (depending on the extension's internal logic). The return value of any loaded file will be cached, so there must either be no dynamic PHP code in it or care must be taken to clear the system cache after each change in such files. See the t3api docs for more information on how extensions can add and change TCA.

The TYPO3 core bootstrap compiles the final TCA on first call by loading all files from the different locations, and caches the result. On subsequent calls this relatively huge array is then rather quickly loaded from cache and is made available as $GLOBALS['TCA'] in almost all normal access patterns like Frontend, Backend and CLI requests.

TCA main array structure

Glossary

Before you read on, let's just refresh the meaning of a few concepts mentioned on the next pages:

TCE

Short for TYPO3 Core Engine. Also referred to as "DataHandler". The corresponding class \TYPO3\CMS\Core\DataHandling\DataHandler should ideally handle all updates to records made in the backend of TYPO3. The class will handle all the rules which may be applied to each table correctly. It will also handle logging, versioning, history and undo features, and copying, moving, deleting etc.

"list of"

Typically used like "list of field names". Whenever "list of" is used it means a list of strings separated by comma and with NO space between the values.

field name

The name of a field from a database table. Another word for the same is "column" but it is used more rarely, however the meaning is exactly the same.

record type

A record can have different types, determined by the value of a certain field in the record. This field is defined by the type property of the [ctrl] section. It affects which fields are displayed in backend form (see the "types" configuration). The record type can be considered as a switch in the interpretation of the whole record.

LLL reference

A localized string fetched from a locallang file by prefixing the string with LLL:.

Extension styleguide

Many of the examples are part of the TYPO3 extension styleguide. This extension offers numbered examples for any field type. Furthermore there are examples with different properties set to different values.

Read here about how to install and use the styleguide extension.

Extension examples

Some examples can also be found in the TYPO3 extension examples. This extension contains special configurations that have not been used in the extension stylguide nor in the TYPO3 Core.

The extension examples can be installed via composer:

composer require --dev t3docs/examples

It can also be downloaded from the TYPO3 extension repository.

Examples from the TYPO3 Core

Some examples are taken from the TYPO3 Core and some come from different system extensions. You can open their TCA definitions in the corresponding file in the system extension.

Common examples are taken from the following tables:

pages

public/typo3/sysext/core/Configuration/TCA/pages.php

sys_category

public/typo3/sysext/core/Configuration/TCA/sys_category.php

sys_file

public/typo3/sysext/core/Configuration/TCA/sys_file.php

sys_template

public/typo3/sysext/frontend/Configuration/TCA/sys_template.php

tt_content

public/typo3/sysext/frontend/Configuration/TCA/tt_content.php

Mandatory fields

If the table has a TCA definition, TYPO3 will automatically create the following fields:

uid

An auto-incrementing unique identifier. This field is used as table key and as a reference in relationships between records.

pid

The uid field of the parent page. The record is situated on this page. If this value is 0 the record is not connected to any page.

There is no separate TCA definition of these fields in the TCA configuration. It is not possible to use other names for these fields.

Fields used by convention

Soft delete

deleted

This field is used to enable soft delete in records. In can be configured by setting ctrl->delete:

EXT:my_extension/Configuration/TCA/tx_myextension_domain_model_something.php

<?php

return [
    'ctrl' => [
        'delete' => 'deleted',
        // ...
    ],
];

Copied!

Warning

If no deleted field is configured, records will be hard deleted. The DataHandler in the backend and Extbase will automatically execute DELETE statements.

The deleted field is never directly visible in backend forms. It is handled separately by the DataHandler. Therefore it needs no definition in the columns section.

Enablecolumns

hidden

This field is used to enable soft hiding of records. In can be configured by setting ctrl->enablecolumns->disabled:

EXT:my_extension/Configuration/TCA/tx_myextension_domain_model_something.php

<?php

return [
    'ctrl' => [
        'enablecolumns' => [
            'disabled' => 'hidden',
        ],
        // ...
    ],
    'palettes' => [
        'visibility' => [
            'showitem' => 'hidden',
        ],
    ],
    'types' => [
        0 => [
            'showitem' => '
                --div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:general,
                    [...],
                --div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:access,
                    --palette--;;visibility,
            ',
        ],
    ],
];

Copied!

starttime and endtime

This field is used to enable records by a starttime and or disable them with an endtime. In can be configured by ctrl->enablecolumns->starttime or endtime:

EXT:my_extension/Configuration/TCA/tx_myextension_domain_model_something.php

<?php

return [
    'ctrl' => [
        'enablecolumns' => [
            'disabled' => 'hidden',
            'starttime' => 'starttime',
            'endtime' => 'endtime',
        ],
        // ...
    ],
    'palettes' => [
        'access' => [
            'showitem' => 'starttime, endtime',
        ],
        'visibility' => [
            'showitem' => 'hidden',
        ],
    ],
    'types' => [
        0 => [
            'showitem' => '
                --div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:general,
                    [...],
                --div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:access,
                    --palette--;;visibility,
                    --palette--;;access,
            ',
        ],
    ],
];

Copied!

fe_group

This field is used to enable soft delete of records. In can be configured by ctrl->enablecolumns->fe_group:

EXT:my_extension/Configuration/TCA/tx_myextension_domain_model_something.php

<?php

return [
    'ctrl' => [
        'enablecolumns' => [
            'fe_group' => 'fe_group',
        ],
        // ...
    ],
    'palettes' => [
        'access' => [
            'label' => 'LLL:EXT:frontend/Resources/Private/Language/locallang_ttc.xlf:palette.access',
            'showitem' => '
                fe_group,
            ',
        ],
    ],
    'types' => [
        0 => [
            'showitem' => '
                --div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:general,
                    [...],
                --div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:access,
                    --palette--;;access,
            ',
        ],
    ],
];

Copied!

Manual sorting in the backend

sorting

This field is used to manually sort records in the backend. In can be configured by ctrl->sortby:

EXT:my_extension/Configuration/TCA/tx_myextension_domain_model_something.php

<?php

return [
    'ctrl' => [
        'sortby' => 'sorting',
    ],
];

Copied!

Fields managed by the DataHandler

The following fields are automatically set when a record is written by the DataHandler. They should never be displayed in backend forms or explicitly set, therefore they need no entry in the Field definitions (columns) section of the TCA.

<?php

return [
    'ctrl' => [
        'tstamp' => 'tstamp',
        'crdate' => 'crdate',
        'origUid' => 't3_origuid',
        // ...
    ],
];

tstamp

This field is automatically updated to the current timestamp each time the record is updated or saved in the DataHandler.

It can be configured by setting ctrl->tstamp.

crdate

This field is automatically set to the current timestamp if the record is created by the DataHandler.

It can be configured by setting ctrl->crdate.

t3_origuid

Field name, which contains the uid of the original record in case a record is created as a copy or new version of another record.

It can be configured by setting ctrl->origUid.

Language fields in detail

sys_language_uid

This field gets defined in ctrl->languageField. If this field is defined a record in this table can be translated into another language.

l10n_parent

This field gets defined in ctrl->transOrigPointerField.

If this value is found being set together with languageField then FormEngine will show the default translation value under the fields in the main form.

Note

Sometimes l18n_parent is used for this field in Core tables. This is for historic reasons.

l10n_source

This field gets defined in ctrl->translationSource.

This field contains the uid of the record the translation was created from. For example if your default language is English and you already translated a record into German you can base the Suisse-German translation on the German record. In this case l10n_parent would contain the uid of the English record while l10n_source contains the uid of the German record.

l10n_diffsource

This field gets defined in ctrl->transOrigPointerField.

This information is used later on to compare the current values of the default record with those stored in this field. If they differ, there will be a display in the form of the difference visually:

Note

Sometimes l18n_diffsource is used for this field in Core tables. This has historic reasons.

Example: Enable table for localization and translation:

<?php

return [
    'ctrl' => [
        'transOrigPointerField' => 'l10n_parent',
        'transOrigDiffSourceField' => 'l10n_diffsource',
        'languageField' => 'sys_language_uid',
        'translationSource' => 'l10n_source',
        // ...
    ],
    'palettes' => [
        'language' => [
            'showitem' => '
                sys_language_uid,l10n_parent,
            ',
        ],
    ],
    'types' => [
        0 => [
            'showitem' => '
                --div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:general,
                    [...],
                --div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:language,
                    --palette--;;language,
            ',
        ],
    ],
];

Example: A basic input field

The basic structure of a field definition in TCA looks like this:

[
    'columns' => [
        'input_1' => [
            'l10n_mode' => 'prefixLangTitle',
            'label' => 'input_1 description',
            'description' => 'field description',
            'config' => [
                'type' => 'input',
                'behaviour' => [
                    'allowLanguageSynchronization' => true,
                ],
            ],
        ],
    ],
]

You can find this example in the extension styleguide.

Properties on the level parallel to label are valid for all "type" and "renderType" combinations. They are listed below. The list of properties within the "config" section depend on the specific "type" and "renderType" combination and are explained in detail in the ['columns']['config'] section.

Properties of columns section of TCA

[
     'columns' => [
          'input_2' => [
                'label' => 'input_2 description',
                'exclude' => true,
                'config' => [
                     'type' => 'input',

                ],
          ],
     ],
]

[
    'columns' => [
        'select_requestUpdate_1' => [
            'label' => 'select_requestUpdate_1',
            'onChange' => 'reload',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectSingle',
                'items' => [
                    [
                        'label' => 'Just an item',
                        'value' => 1,
                    ],
                    [
                        'label' => 'bar',
                        'value' => 'bar',
                    ],
                    [
                        'label' => 'and yet another one',
                        'value' => -1,
                    ],
                ],
            ],
        ],
    ],
]

Rules in display conditions

A rule is a string divided into several parts by ":" (colons). The first part is the rule-type and the subsequent parts depend on the rule type.

The following rules are available:

FIELD

This evaluates based on another field's value in the record.

• Part 1 is the field name

• Part 2 is the evaluation type. These are the possible options:

  REQ

  Requires the field to have a "true" value. False values are "" (blank string) and 0 (zero). Everything else is true. For the REQ evaluation type Part 3 of the rules string must be the string "true" or "false". If "true" then the rule returns "true" if the evaluation is true. If "false" then the rule returns "true" if the evaluation is false.

  > / < / >= / <=

  Evaluates if the field value is greater than, less than the value in "Part 3"

  = / !=

  Evaluates if the field value is equal to value in "Part 3"

  IN / !IN

  Evaluates if the field value is in the comma list equal to value in "Part 3"

  - / !-

  Evaluates if the field value is in the range specified by value in "Part 3" ([min] - [max])

  BIT / !BIT

  Evaluates if the bit specified by the value in "Part 3" is set in the field's value (considered as an integer)

• Part 3 is a comma separated list of string or numeric values

REC:NEW:true

This will show the field for new records which have not been saved yet.

REC:NEW:false

This will show the field for existing records which have already been saved.

HIDE_FOR_NON_ADMINS

This will hide the field for all non-admin users while admins can see it. Useful for FlexForm container fields which are not supposed to be edited directly via the FlexForm but rather through some other interface.

USER

userFunc call with a fully qualified class name.

Additional parameters can be passed separated by colon: USER:Evoweb\\Example\\User\\MyConditionMatcher->checkHeader:some:more:info

The following arguments are passed as array to the userFunc:

• record: the currently edited record
• flexContext: details about the FlexForm if the condition is used in one
• flexformValueKey: vDEF
• conditionParameters: additional parameters

The called method is expected to return a bool value: true if the field should be displayed, false otherwise.

VERSION:IS

Evaluate if a record is a "versioned" record from workspaces.

• Part 1 is the type:

  IS

  Part 2 is "true" or "false": If true, the field is shown only if the record is a version (pid == -1). Example to show a field in "Live" workspace only: VERSION:IS:false

In FlexForm, display conditions can be attached to single fields in sheets, to sheets itself, to flex section fields and to flex section container element fields. FIELD references can be prefixed with a sheet name to reference a field from a neighbor sheet, see examples below.

Examples for display conditions

'displayCond' => 'FIELD:tx_templavoila_ds:REQ:true',

'displayCond' => [
    'AND' => [
        'FIELD:tx_templavoila_ds:REQ:true',
        'FIELD:header:=:Headline',
    ],
],

$GLOBALS['TCA']['tx_mask_table']['columns']['tx_mask_field']['displayCond']['OR'] = [
    'FIELD:tx_mask_otherfield:=:1',
    'FIELD:tx_mask_otherfield:=:2',
    'FIELD:tx_mask_otherfield:=:4',
];

      $GLOBALS['TCA']['tx_mask_table']['columns']['tx_mask_field']['displayCond']
= 'FIELD:tx_mask_otherfield:IN:1,2,4';

'displayCond' => [
    'AND' => [
        'FIELD:sys_language_uid:=:0',
        'OR' => [
            'FIELD:CType:=:text',
            'FIELD:header:=:Example'
        ]
    ]
],

<displayCond>
    <and>
        <value1>FIELD:sys_language_uid:=:0</value1>
        <or>
            <value1>FIELD:CType:=:text</value1>
            <value2>FIELD:header:=:Example</value2>
        </or>
    </and>
</displayCond>

<!-- Hide field if value of record field "header" is not "true" -->
<displayCond>FIELD:parentRec.header:REQ:true</displayCond>
<!-- Hide field if value of parent record field "field_1" is not "foo" -->
<displayCond>FIELD:parentRec.field_1:!=:foo</displayCond>
<!-- Hide field if value of neighbour field "flexField_1 on same sheet is not "foo" -->
<displayCond>FIELD:flexField_1:!=:foo</displayCond>
<!-- Hide field if value of field "flexField_1" from sheet "sheet_1" is not "foo" -->
<displayCond>FIELD:sheet_1.flexField_1:!=:foo</displayCond>

Technical background

The display conditions are implemented in class \TYPO3\CMS\Backend\Form\FormDataProvider\EvaluateDisplayConditions , which is a FormDataProvider. It can be used for fields directly in the record as well as for FlexForm values.

Select drop-down for records represented by images

Select field with foreign table relation and field wizard:

[
    'columns' => [
        'select_single_12' => [
            'label' => 'select_single_12 foreign_table selicon_field',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectSingle',
                'foreign_table' => 'tx_styleguide_elements_select_single_12_foreign',
                'fieldWizard' => [
                    'selectIcons' => [
                        'disabled' => false,
                    ],
                ],
            ],
        ],
    ],
]

The table tx_styleguide_elements_select_single_12_foreign is defined as follows:

[
   'ctrl' => [
      'title' => 'Form engine elements - select foreign single_12',
      'label' => 'fal_1',
      'selicon_field' => 'fal_1',
      // ...
   ],

   'columns' => [
      // ...
      'fal_1' => [
         'label' => 'fal_1 selicon_field',
         'config' => \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::getFileFieldTCAConfig(
            'fal_1',
            [
               'maxitems' => 1,
            ],
            $GLOBALS['TYPO3_CONF_VARS']['SYS']['mediafile_ext']
         ),
      ],
   ],
   // ...

];

Inline relation (IRRE) spanning multiple tables

Inline relation to a foreign table:

[
    'columns' => [
        'inline_1' => [
            'label' => 'inline_1',
            'config' => [
                'type' => 'inline',
                'foreign_table' => 'tx_styleguide_inline_1n1n_child',
                'foreign_field' => 'parentid',
                'foreign_table_field' => 'parenttable',
            ],
        ],
    ],
]

Example: prefixLangTitle

The following example can be found in the extension styleguide. On translating a record in a new language the content of the field gets copied to the target language. It get prefixed with [Translate to <language name>:].

The language mode is defined as follows:

[
    'columns' => [
        'text_2' => [
            'l10n_mode' => 'prefixLangTitle',
            'label' => 'text_2',
            'description' => 'cols=20',
            'config' => [
                'type' => 'text',
                'cols' => 20,
            ],
        ],
    ],
]

Disable the prefixLangTitle for the header field in tt_content

Use the default behaviour instead of prefixLangTitle: the field will be copied without a prepended string.

$GLOBALS['TCA']['tt_content']['columns']['header']['l10n_mode'] = ''

Select field with defaultAsReadonly

The following field has the option 'l10n_display' => 'defaultAsReadonly' set:

Complete TCA definition of the field:

[
    'columns' => [
        'select_single_13' => [
            'label' => 'select_single_13 l10n_display=defaultAsReadonly',
            'l10n_mode' => 'exclude',
            'l10n_display' => 'defaultAsReadonly',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectSingle',
                'items' => [
                    [
                        'label' => 'foo',
                        'value' => 'foo',
                    ],
                    [
                        'label' => 'bar',
                        'value' => 'bar',
                    ],
                ],
            ],
        ],
    ],
]

Translated field without l10n_display definition

The following has no 'l10n_display' definition:

Complete TCA definition of the field:

[
    'columns' => [
        'select_single_8' => [
            'label' => 'select_single_8 drop down with empty div',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectSingle',
                'items' => [
                    [
                        'label' => 'First div with items',
                        'value' => '--div--',
                    ],
                    [
                        'label' => 'item 1',
                        'value' => 1,
                    ],
                    [
                        'label' => 'item 2',
                        'value' => 2,
                    ],
                    [
                        'label' => 'Second div without items',
                        'value' => '--div--',
                    ],
                    [
                        'label' => 'Third div with items',
                        'value' => '--div--',
                    ],
                    [
                        'label' => 'item 3',
                        'value' => 3,
                    ],
                ],
            ],
        ],
    ],
]

Example

You can have a look at the extension georgringer/news in version 9.4 for an example: https://github.com/georgringer/news/blob/9.4.0/Configuration/TCA/tx_news_domain_model_news.php#L521 (with georgringer/news ^10.0 this was moved to a non-public extension).

'tags' => [
    'config' => [
        // ...
        'fieldInformation' => [
            'tagInformation' => [
                'renderType' => 'NewsStaticText',
                'options' => [
                    'labels' => [
                        [
                            'label' => '',
                            'bold' => true,
                            'italic' => true,
                        ],
                    ],
                ],
            ],
        ],
    ]

The implementation can be found in https://github.com/georgringer/news/blob/9.4.0/Classes/Backend/FieldInformation/StaticText.php:

<?php

declare(strict_types=1);

namespace GeorgRinger\News\Backend\FieldInformation;

use TYPO3\CMS\Backend\Form\AbstractNode;

class StaticText extends AbstractNode
{
    public function render(): array
    {
        // ...

        return [
            'requireJsModules' => [
                'TYPO3/CMS/News/TagSuggestWizard',
            ],
            'html' => '...>',
        ];
    }
}

The custom FieldInformation must be rendered in ext_localconf.php:

$GLOBALS['TYPO3_CONF_VARS']['SYS']['formEngine']['nodeRegistry'][1552726986] = [
    'nodeName' => 'NewsStaticText',
    'priority' => 70,
    'class' => \GeorgRinger\News\Backend\FieldInformation\StaticText::class
];

Passed parameters

• items (passed by reference)
• config (TCA config of the field)
• TSconfig (The matching itemsProcFunc TSconfig)
• table (current table)
• row (current database record)
• field (current field name)
• effectivePid (correct page ID)
• site (current site)

The following parameter only exists if the field has a flex parent.

• flexParentDatabaseRow

The following parameters are filled if the current record has an inline parent.

• inlineParentUid
• inlineParentTableName
• inlineParentFieldName
• inlineParentConfig
• inlineTopMostParentUid
• inlineTopMostParentTableName
• inlineTopMostParentFieldName

Example

The configuration for a custom field select_single_2 could look like this:

'select_single_2' => [
    'exclude' => 1,
    'label' => 'select_single_2 itemsProcFunc',
    'config' => [
        'type' => 'select',
        'renderType' => 'selectSingle',
        'items' => [
            ['label' => 'foo', 'value' => 1],
            ['label' => 'bar', 'value' => 'bar'],
        ],
        'itemsProcFunc' => TYPO3\CMS\Styleguide\UserFunctions\FormEngine\TypeSelect2ItemsProcFunc::class . '->itemsProcFunc',
    ],
]

The referenced itemsProcFunc method should populate the items by filling $params['items']:

/**
 * A user function used in select_2
 */
class TypeSelect2ItemsProcFunc
{
    /**
     * Add two items to existing ones
     *
     * @param array $params
     */
    public function itemsProcFunc(&$params): void
    {
        $params['items'][] = ['label' => 'item 1 from itemProcFunc()', 'value' => 'val1'];
        $params['items'][] = ['label' => 'item 2 from itemProcFunc()', 'value' => 'val2'];
    }
}

This results in the rendered select dropdown having four items. This is a really simple example. In the real world you would use the other passed parameters to dynamically generate the items.

MM relations and FlexForms

MM relations has been tested to work with FlexForms if not in a repeated element in a section.

Related configurations

Auto creation of intermediate MM tables from TCA

TCA table column fields that define ['config']['MM'] can drop specification of the intermediate mm table layout in: ext_tables.sql. The TYPO3 database analyzer takes care of proper schema definition.

Extensions are strongly encouraged to drop ext_tables.sql CREATE TABLE definitions for those intermediate tables referenced by TCA table columns. Dropping these definitions allows the Core to adapt and migrate definitions if needed.

The mm tables are automatically created if:

• A table column TCA config defines MM with type='select', type='group' or type='inline'.
• The "MM" intermediate table has no TCA table definition (!).
• A table of the resulting name is not defined in ext_tables.sql.

The schema analyzer takes care of further possible fields apart from uid_local and uid_foreign, like tablenames, fieldname and uid if necessary, depending on local side of the TCA definition.

The fields used for sorting sorting and sorting_foreign are always created, they do not need to be defined in TCA.

...
'columns' => [
    ...
    'myField' => [
        'label' => 'myField',
        'config' => [
            'type' => 'group',
            'foreign_table' => 'tx_myextension_myfield_child',
            'MM' => 'tx_myextension_myfield_mm',
        ]
    ],
    ...
],
...

CREATE TABLE tx_myextension_myfield_mm (
    uid_local int(11) DEFAULT '0' NOT NULL,
    uid_foreign int(11) DEFAULT '0' NOT NULL,
    sorting int(11) DEFAULT '0' NOT NULL,
    sorting_foreign int(11) DEFAULT '0' NOT NULL,

    KEY uid_local (uid_local),
    KEY uid_foreign (uid_foreign)
);

Examples

Select field

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_select.php

[
    'columns' => [
        'select_multiplesidebyside_6' => [
            'label' => 'select_multiplesidebyside_6 fieldControl',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectMultipleSideBySide',
                'foreign_table' => 'tx_styleguide_staticdata',
                'size' => 5,
                'autoSizeMax' => 20,
                'fieldControl' => [
                    'editPopup' => [
                        'disabled' => false,
                        'options' => [
                            'windowOpenParameters' => 'height=300,width=500,status=0,menubar=0,scrollbars=1',
                        ],
                    ],
                    'addRecord' => [
                        'disabled' => false,
                    ],
                    'listModule' => [
                        'disabled' => false,
                    ],
                ],
            ],
        ],
    ],
]

Copied!

Group field

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_group.php

[
    'columns' => [
        'group_db_1' => [
            'label' => 'group_db_1 allowed=be_users,be_groups description',
            'description' => 'field description',
            'config' => [
                'type' => 'group',
                'allowed' => 'be_users,be_groups',
                'fieldControl' => [
                    'editPopup' => [
                        'disabled' => false,
                    ],
                    'addRecord' => [
                        'disabled' => false,
                    ],
                    'listModule' => [
                        'disabled' => false,
                    ],
                ],
            ],
        ],
    ],
]

Copied!

Select field with options

The field controls are also used in the core. The following example is from the table be_groups:

EXT:core/Configuration/TCA/be_groups.php

[
    'columns' => [
        'file_mountpoints' => [
            'label' => 'LLL:EXT:core/Resources/Private/Language/locallang_tca.xlf:file_mountpoints',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectMultipleSideBySide',
                'foreign_table' => 'sys_filemounts',
                'foreign_table_where' => ' AND {#sys_filemounts}.{#pid}=0',
                'size' => 3,
                'autoSizeMax' => 10,
                'fieldControl' => [
                    'editPopup' => [
                        'disabled' => false,
                        'options' => [
                            'title' => 'LLL:EXT:core/Resources/Private/Language/locallang_tca.xlf:file_mountpoints_edit_title',
                        ],
                    ],
                    'addRecord' => [
                        'disabled' => false,
                        'options' => [
                            'title' => 'LLL:EXT:core/Resources/Private/Language/locallang_tca.xlf:file_mountpoints_add_title',
                            'setValue' => 'prepend',
                        ],
                    ],
                    'listModule' => [
                        'disabled' => false,
                        'options' => [
                            'title' => 'LLL:EXT:core/Resources/Private/Language/locallang_tca.xlf:file_mountpoints_list_title',
                        ],
                    ],
                ],
            ],
        ],
    ],
]

Copied!

Options

Options

Examples

Select field

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_select.php

[
    'columns' => [
        'select_multiplesidebyside_6' => [
            'label' => 'select_multiplesidebyside_6 fieldControl',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectMultipleSideBySide',
                'foreign_table' => 'tx_styleguide_staticdata',
                'size' => 5,
                'autoSizeMax' => 20,
                'fieldControl' => [
                    'editPopup' => [
                        'disabled' => false,
                        'options' => [
                            'windowOpenParameters' => 'height=300,width=500,status=0,menubar=0,scrollbars=1',
                        ],
                    ],
                    'addRecord' => [
                        'disabled' => false,
                    ],
                    'listModule' => [
                        'disabled' => false,
                    ],
                ],
            ],
        ],
    ],
]

Copied!

Group field

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_group.php

[
    'columns' => [
        'group_db_1' => [
            'label' => 'group_db_1 allowed=be_users,be_groups description',
            'description' => 'field description',
            'config' => [
                'type' => 'group',
                'allowed' => 'be_users,be_groups',
                'fieldControl' => [
                    'editPopup' => [
                        'disabled' => false,
                    ],
                    'addRecord' => [
                        'disabled' => false,
                    ],
                    'listModule' => [
                        'disabled' => false,
                    ],
                ],
            ],
        ],
    ],
]

Copied!

Options

Examples

Select field

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_select.php

[
    'columns' => [
        'select_multiplesidebyside_6' => [
            'label' => 'select_multiplesidebyside_6 fieldControl',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectMultipleSideBySide',
                'foreign_table' => 'tx_styleguide_staticdata',
                'size' => 5,
                'autoSizeMax' => 20,
                'fieldControl' => [
                    'editPopup' => [
                        'disabled' => false,
                        'options' => [
                            'windowOpenParameters' => 'height=300,width=500,status=0,menubar=0,scrollbars=1',
                        ],
                    ],
                    'addRecord' => [
                        'disabled' => false,
                    ],
                    'listModule' => [
                        'disabled' => false,
                    ],
                ],
            ],
        ],
    ],
]

Copied!

Group field

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_group.php

[
    'columns' => [
        'group_db_1' => [
            'label' => 'group_db_1 allowed=be_users,be_groups description',
            'description' => 'field description',
            'config' => [
                'type' => 'group',
                'allowed' => 'be_users,be_groups',
                'fieldControl' => [
                    'editPopup' => [
                        'disabled' => false,
                    ],
                    'addRecord' => [
                        'disabled' => false,
                    ],
                    'listModule' => [
                        'disabled' => false,
                    ],
                ],
            ],
        ],
    ],
]

Copied!

Properties of the TCA column type category

Simple category field

In the following example a category tree is displayed and multiple categories can be selected.

<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

$GLOBALS['TCA'][$myTable]['columns']['categories'] = [
    'config' => [
        'type' => 'category',
    ],
];

ExtensionManagementUtility::addToAllTCAtypes(
    $myTable,
    'categories'
);

The relationship gets stored in the intermediate table sys_category_record_mm. Category counts are only stored on the local side.

One to one relation category field

In the following example a category tree is displayed, but only one category can be selected.

<?php

$GLOBALS['TCA'][$myTable]['columns']['mainCategory'] = [
    'config' => [
        'type' => 'category',
        'relationship' => 'oneToOne',
    ],
];

Category field used in FlexForm

It is possible to use the type category in FlexForm data structures. Due to some limitations in FlexForm, the manyToMany relationship is not supported. Therefore, the default relationship - used if none is defined - is oneToMany.

An example of the "oneToMany" use case is EXT:news, which allows to only display news of specific categories in the list view:

<T3DataStructure>
    <ROOT>
        <sheetTitle>aTitle</sheetTitle>
        <type>array</type>
        <el>
            <categories>
                <config>
                    <type>category</type>
                </config>
            </categories>
        </el>
    </ROOT>
</T3DataStructure>

Introduction

This type creates checkbox(es).

There can be between 1 and 31 checkboxes. The corresponding database field must be of type integer. Each checkbox corresponds to a single bit of the integer value, even if there is only one checkbox.

There is a subtle difference between fields of the type check and select fields with the render type selectCheckBox. For the details please see: selectCheckBox and type check fields compared.

The following renderTypes are available:

• default: One or more checkboxes are displayed.
• checkboxToggle: Instead of checkboxes, a toggle item is displayed.
• checkboxLabeledToggle: A toggle switch where both states can be labelled (ON/OFF, Visible / Hidden or alike). Its state can be inverted via invertStateDisplay

Properties of the TCA column type check

Examples Fixes columns -------------

[
    'columns' => [
        'checkbox_2' => [
            'label' => 'checkbox_2',
            'description' => 'one checkbox with label',
            'config' => [
                'type' => 'check',
                'items' => [
                    [
                        'label' => 'foo',
                    ],
                ],
            ],
        ],
    ],
]

Examples

All examples listed here can be found in the extension styleguide.

Example: Simple checkbox with label

TCA:

[
    'columns' => [
        'checkbox_2' => [
            'label' => 'checkbox_2',
            'description' => 'one checkbox with label',
            'config' => [
                'type' => 'check',
                'items' => [
                    [
                        'label' => 'foo',
                    ],
                ],
            ],
        ],
    ],
]

If the checkbox is checked, the value for the field will be 1, if unchecked, it will be 0.

FlexForm:

<checkbox_2>
   <label>checkbox_2 cols=3</label>
   <config>
       <type>check</type>
       <items type="array">
           <numIndex index="0" type="array">
               <label>foo1</label>
               <value></value>
           </numIndex>
           <numIndex index="1" type="array">
               <label>foo2</label>
               <value></value>
           </numIndex>
           <numIndex index="2" type="array">
               <label>foo3</label>
               <value></value>
           </numIndex>
           <numIndex index="3" type="array">
               <label>foo4</label>
               <value></value>
           </numIndex>
       </items>
       <cols>3</cols>
   </config>
</checkbox_2>

Example: Four checkboxes in three columns

TCA:

[
    'columns' => [
        'checkbox_12' => [
            'label' => 'checkbox_12',
            'description' => 'cols=3',
            'config' => [
                'type' => 'check',
                'items' => [
                    [
                        'label' => 'foo1',
                    ],
                    [
                        'label' => 'foo2',
                    ],
                    [
                        'label' => 'foo3',
                    ],
                    [
                        'label' => 'foo4',
                    ],
                ],
                'cols' => '3',
            ],
        ],
    ],
]

If all checkboxes are checked, the value for the field will be 15 (1 | 2 | 4 | 8).

Example: Checkboxes with inline floating

[
    'columns' => [
        'checkbox_16' => [
            'label' => 'checkbox_16',
            'description' => 'cols=inline',
            'config' => [
                'type' => 'check',
                'items' => [
                    [
                        'label' => 'Mo',
                    ],
                    [
                        'label' => 'Tu',
                    ],
                    [
                        'label' => 'We',
                    ],
                    [
                        'label' => 'Th',
                    ],
                    [
                        'label' => 'Fr',
                    ],
                    [
                        'label' => 'Sa',
                    ],
                    [
                        'label' => 'Su',
                    ],
                ],
                'cols' => 'inline',
            ],
        ],
    ],
]

This will display as many checkbox items as will fit in one row. Without inline, each checkbox would be displayed in a separate row.

Examples

Example: Single checkbox with toggle

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_basic.php

[
    'columns' => [
        'checkbox_17' => [
            'label' => 'checkbox_17',
            'description' => 'renderType=checkboxToggle single',
            'config' => [
                'type' => 'check',
                'renderType' => 'checkboxToggle',
                'items' => [
                    [
                        'label' => 'foo',
                    ],
                ],
            ],
        ],
    ],
]

Copied!

checkboxToggle: Instead of checkboxes, a toggle item is displayed.

Example: Single checkbox with toggle inverted state display

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_basic.php

[
    'columns' => [
        'checkbox_18' => [
            'label' => 'checkbox_18',
            'description' => 'renderType=checkboxToggle single inverted state display',
            'config' => [
                'type' => 'check',
                'renderType' => 'checkboxToggle',
                'items' => [
                    [
                        'label' => 'foo',
                        'invertStateDisplay' => true,
                    ],
                ],
            ],
        ],
    ],
]

Copied!

invertedStateDisplay: A checkbox is marked checked if the database bit is not set and vice versa.

Examples

Single checkbox with labeled toggle

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_basic.php

[
    'columns' => [
        'checkbox_19' => [
            'label' => 'checkbox_19',
            'description' => 'renderType=checkboxLabeledToggle single',
            'config' => [
                'type' => 'check',
                'renderType' => 'checkboxLabeledToggle',
                'items' => [
                    [
                        'label' => 'foo',
                        'labelChecked' => 'Enabled',
                        'labelUnchecked' => 'Disabled',
                    ],
                ],
            ],
        ],
    ],
]

Copied!

Single checkbox with labeled toggle inverted state display

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_basic.php

[
    'columns' => [
        'checkbox_21' => [
            'label' => 'checkbox_21',
            'description' => 'renderType=checkboxLabeledToggle single inverted state display',
            'config' => [
                'type' => 'check',
                'renderType' => 'checkboxLabeledToggle',
                'items' => [
                    [
                        'label' => 'foo',
                        'labelChecked' => 'Enabled',
                        'labelUnchecked' => 'Disabled',
                        'invertStateDisplay' => true,
                    ],
                ],
            ],
        ],
    ],
]

Copied!

Example: Default checkboxes with fixed columns

[
    'columns' => [
        'checkbox_2' => [
            'label' => 'checkbox_2',
            'description' => 'one checkbox with label',
            'config' => [
                'type' => 'check',
                'items' => [
                    [
                        'label' => 'foo',
                    ],
                ],
            ],
        ],
    ],
]

Example: Checkboxes with Inline columns and default value

Here "Tu", the second bit, is active by default.

[
    'columns' => [
        'checkbox_16' => [
            'label' => 'checkbox_16',
            'description' => 'cols=inline',
            'config' => [
                'type' => 'check',
                'items' => [
                    [
                        'label' => 'Mo',
                    ],
                    [
                        'label' => 'Tu',
                    ],
                    [
                        'label' => 'We',
                    ],
                    [
                        'label' => 'Th',
                    ],
                    [
                        'label' => 'Fr',
                    ],
                    [
                        'label' => 'Sa',
                    ],
                    [
                        'label' => 'Su',
                    ],
                ],
                'cols' => 'inline',
            ],
        ],
    ],
]

Example: Checkbox limited to a maximal number of checked records

[
    'columns' => [
        'checkbox_7' => [
            'label' => 'checkbox_7',
            'description' => 'eval=maximumRecordsChecked, table wide',
            'config' => [
                'type' => 'check',
                'eval' => 'maximumRecordsChecked',
                'validation' => [
                    'maximumRecordsChecked' => 1,
                ],
            ],
        ],
    ],
]

Example: Toggle checkbox with invertStateDisplay

[
    'columns' => [
        'checkbox_18' => [
            'label' => 'checkbox_18',
            'description' => 'renderType=checkboxToggle single inverted state display',
            'config' => [
                'type' => 'check',
                'renderType' => 'checkboxToggle',
                'items' => [
                    [
                        'label' => 'foo',
                        'invertStateDisplay' => true,
                    ],
                ],
            ],
        ],
    ],
]

Example: Three checkboxes, two with labels, one without

[
    'columns' => [
        'checkbox_3' => [
            'label' => 'checkbox_3',
            'description' => 'three checkboxes, two with labels, one without',
            'config' => [
                'type' => 'check',
                'items' => [
                    [
                        'label' => 'foo',
                    ],
                    [
                        'label' => '',
                    ],
                    [
                        'label' => 'foobar',
                        'iconIdentifierChecked' => 'content-beside-text-img-below-center',
                        'iconIdentifierUnchecked' => 'content-beside-text-img-below-center',
                    ],
                ],
            ],
        ],
    ],
]

Example: Checkboxes with itemsProcFunc

The configuration for a custom field select_single_2 could look like this:

<?php

use MyVendor\MyExtension\UserFunctions\MyItemsProcFunc;

return [
    'columns' => [
        'checkbox_itemsProcFunc' => [
            'exclude' => 1,
            'label' => 'checkbox itemsProcFunc',
            'config' => [
                'type' => 'check',
                'items' => [
                    ['label' => 'foo', 'value' => 1],
                    ['label' => 'bar', 'value' => 'bar'],
                ],
                'itemsProcFunc' => MyItemsProcFunc::class . '->itemsProcFunc',
            ],
        ],
    ],
];

The referenced itemsProcFunc method should populate the items by filling $params['items']:

<?php

class MyItemsProcFunc
{
    /**
     * Add two items to existing ones
     */
    public function itemsProcFunc(array &$params): void
    {
        $params['items'][] = ['label' => 'item 1 from itemProcFunc()', 'value' => 'val1'];
        $params['items'][] = ['label' => 'item 2 from itemProcFunc()', 'value' => 'val2'];
    }
}

In the real world you would use the other passed parameters to dynamically generate the items.

Example: checkboxToggle

Example: checkboxLabeledToggle

Example: Only one record can be checked

In the example below, only one record from the same table will be allowed to have that particular box checked.

[
    'columns' => [
        'checkbox_8' => [
            'label' => 'checkbox_8',
            'description' => 'eval=maximumRecordsCheckedInPid, for this PID',
            'config' => [
                'type' => 'check',
                'eval' => 'maximumRecordsCheckedInPid',
                'validation' => [
                    'maximumRecordsCheckedInPid' => 1,
                ],
            ],
        ],
    ],
]

Example: Define a simple color picker in TCA

A simple color picker:

$aColorField' = [
    'label' => 'Color field',
    'config' => [
        'type' => 'color',
    ]
];

Properties of the TCA column type color

Example:

..  _columns-color-properties-nullable:

..  confval:: nullable
    :name: color-nullable
    :Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
    :type: boolean
    :Default: false
    :Scope: Proc

    If set to true, a checkbox will appear, which by default deactivates the
    field. In the deactivated state the field is saved as :sql:`NULL` in the
    database. By activating the checkbox it is possible to set a value.
    If nothing is entered into the field, then an empty string will be
    saved and not a :sql:`NULL`.

    The database field must allow the :sql:`NULL` value.

Example:

..  literalinclude:: _Properties/_Nullable.rst.txt
    :caption: EXT:some_extension/Configuration/TCA/tx_sometable.php

$temporaryColumns['aColorField'] = [
    'label' => 'My Color',
    'config' => [
        'type' => 'color',
        'opacity' => true,
    ],
];

<?php

$temporaryColumns['aColorField'] = [
    'label' => 'Color field',
    'config' => [
        'type' => 'color',
        'required' => true,
        'size' => 20,
        'valuePicker' => [
            'items' => [
                ['typo3 orange', '#FF8700'],
            ],
        ],
    ],
];

Example: A simple date field, stored as bigint

A simple date field, stored as bigint in the database:

<?php

$temporaryColumns['my-date'] = [
    'label' => 'Datetime field',
    'config' => [
        'type' => 'datetime',
        'format' => 'date',
        'default' => 0,
    ],
];

Properties of the TCA column type datetime

CREATE TABLE tx_example_domain_model_foo (
  synced_at datetime default NULL
)

<?php

$temporaryColumns['synced_at'] = [
    'config' => [
        'type' => 'datetime',
        'dbType' => 'datetime',
        'nullable' => true,
    ],
];

CREATE TABLE tx_example_domain_model_foo (
   synced_at time default NULL
)

<?php

$temporaryColumns['synced_at'] =  [
    'config' => [
        'type' => 'datetime',
        'dbType' => 'time',
        'format' => 'time',
        'nullable' => true,
    ],
];

<?php

$temporaryColumns['my-date'] = [
    'title' => 'A nullable date',
    'config' => [
        'type' => 'datetime',
        'nullable' => true,
    ],
];