Model: a bag of tea

We keep the model basic: Each tea can have a title, a description, and an optional image.

class Tea {

The title and description are strings, the image is stored as a relation to the model class \TYPO3\CMS\Extbase\Domain\Model\FileReference, provided by Extbase.

The database model

Let us translate this into SQL and store the schema in a file called ext_tables.sql:

CREATE TABLE tx_tea_domain_model_product_tea (
    title       varchar(255)     DEFAULT ''  NOT NULL,
    description varchar(2000)    DEFAULT ''  NOT NULL,
    image       int(11) unsigned DEFAULT '0' NOT NULL

The image is stored as an integer. However the field image in the database does not contains a reference to the image in form of an identifier.

The field image keeps track of the number of attached images. A separate table, a so-called MM table, stores the actual relationship. Read about the definition of this field here: The image field.


If you have had a look at a TYPO3 database before, you might wonder: What about all those special fields like uid, pid, deleted, etc? The answer is that TYPO3 will generate them automatically for you.

TCA - Table Configuration Array

The TCA tells TYPO3 about the database model. It defines all fields containing data and all semantic fields that have a special meaning within TYPO3 (like the deleted field which is used for soft deletion).

The TCA also defines how the corresponding input fields in the backend should look.

The TCA is a nested PHP array. In this example, we need the the following keys on the first level:


Settings for the complete table, such as a record title, a label for a single record, default sorting, and the names of some internal fields.


Here we define all fields that can be used for user input in the backend.


We only have one type of tea record, however it is mandatory to describe at least one type. Here we define the order in which the fields are displayed in the backend.

TCA ctrl - Settings for the complete table

 2    'ctrl' => [
 3        'title' => 'LLL:EXT:tea/Resources/Private/Language/locallang_db.xlf:tx_tea_domain_model_product_tea',
 4        'label' => 'title',
 5        'tstamp' => 'tstamp',
 6        'crdate' => 'crdate',
 7        'delete' => 'deleted',
 8        'default_sortby' => 'title',
 9        'iconfile' => 'EXT:tea/Resources/Public/Icons/Record.svg',
10        'searchFields' => 'title, description',
11    ],


Defines the title used when we are talking about the table in the backend. It will be displayed on top of the list view of records in the backend and in backend forms.


The title of the tea table.

Strings starting with LLL: will be replaced with localized text. See chapter Extension localization. All other strings will be output as they are. This title will always be output as "Tea" without localization:

    'ctrl' => [
        'title' => 'Tea',


The label is used as name for a specific tea record. The name is used in listings and in backend forms:


The label of a tea record.

tstamp, deleted, ...

These fields are used to keep timestamp and status information for each record. You can read more about them in the TCA Reference, chapter ctrl <t3tca:ctrl>.

TCA columns - Defining the fields

All fields that can be changed in the TYPO3 backend or used in the Extbase model have to be listed here. Otherwise they will not be recognized by TYPO3.

The title field is defined like this:

 2    'columns' => [
 3        'title' => [
 4            'label' => 'LLL:EXT:tea/Resources/Private/Language/locallang_db.xlf:tx_tea_domain_model_product_tea.title',
 5            'config' => [
 6                'type' => 'input',
 7                'size' => 40,
 8                'max' => 255,
 9                'eval' => 'trim',
10                'required' => true,
11            ],
12        ],
13    ],

The title of the field is displayed above the input field. The type is a (string) input field. The other configuration values influence display (size of the input field) and or processing on saving ( 'eval' => 'trim' removes whitespace).

You can find a complete list of available input types and their propererties in the TCA Reference, chapter "Field types (config > type)".

The other text fields are defined in a similar manner.

The image field

The image field is a special case, as it is created by a call to the API function \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::getFileFieldTCAConfig(). This method returns a preconfigured array, and saves you from writing a long and complicated configuration array.

    'columns' => [
        'image' => [
            'label' => 'LLL:EXT:tea/Resources/Private/Language/locallang_db.xlf:tx_tea_domain_model_product_tea.image',
            'config' => \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::getFileFieldTCAConfig(
                    'maxitems' => 1,
                    'appearance' => [
                        'collapseAll' => true,
                        'useSortable' => false,
                        'enabledControls' => [
                            'hide' => false,


Do not worry about performance caused by the API call, the TCA files are cached in compiled form.

The array generated by the method ExtensionManagementUtility::getFileFieldTCAConfig() looks like this:

 2    'columns' => [
 3        'image' => [
 4            'label' => 'LLL:EXT:tea/Resources/Private/Language/locallang_db.xlf:tx_tea_domain_model_product_tea.image',
 5            'config' => [
 6                'type' => 'inline',
 7                'foreign_table' => 'sys_file_reference',
 8                'foreign_field' => 'uid_foreign',
 9                'foreign_sortby' => 'sorting_foreign',
10                'foreign_table_field' => 'tablenames',
11                'foreign_match_fields' => [
12                    'fieldname' => 'image',
13                ],
14                'foreign_label' => 'uid_local',
15                'foreign_selector' => 'uid_local',
16                'overrideChildTca' => [
17                    'columns' => [
18                        'uid_local' => [
19                            'config' => [
20                                'appearance' => [
21                                    'elementBrowserType' => 'file',
22                                    'elementBrowserAllowed' => '',
23                                ],
24                            ],
25                        ],
26                    ],
27                ],
28                'filter' => [
29                    [
30                        'userFunc' => 'TYPO3\\CMS\\Core\\Resource\\Filter\\FileExtensionFilter->filterInlineChildren',
31                        'parameters' => [
32                            'allowedFileExtensions' => '',
33                            'disallowedFileExtensions' => '',
34                        ],
35                    ],
36                ],
37                'appearance' => [
38                    'useSortable' => false,
39                    'headerThumbnail' => [
40                        'field' => 'uid_local',
41                        'height' => '45m',
42                    ],
43                    'enabledControls' => [
44                        'info' => true,
45                        'new' => false,
46                        'dragdrop' => true,
47                        'sort' => false,
48                        'hide' => false,
49                        'delete' => true,
50                    ],
51                    'collapseAll' => true,
52                ],
53                'maxitems' => 1,
54            ],
55        ],
56    ],

You are probably happy that this was generated for you and that you did not have to type it yourself.

TCA types - Configure the input form

2    'types' => [
3        1 => [
4            'showitem' => 'title, description, image',
5        ],
6    ],

The key showitem lists all fields that should be displayed in the backend input form, in the order they should be displayed.


There are more sophisticated ways to influence how the fields are displayed: You can order them in tabs, put them into palettes etc. See TCA reference, showitem for details.

Result - the complete TCA

Have a look at the complete file EXT:tea/Configuration/TCA/tx_tea_domain_model_product_tea.php.

Now the edit form for tea records will look like this:


The complete input form for a tea record.

The list of teas in the module Web -> List looks like this:


A list of teas in the backend.


Up to this point we have only used TYPO3 Core features. You can create tables and backend forms exactly the same way without using Extbase.

The Extbase model

It is a common practice — though not mandatory — to use PHP objects to store the data while working on it.

The model is a more abstract representation of the database schema. It provides more advanced data types, way beyond what the database itself can offer. The model can also be used to define validators for the model properties and to specify relationship types and rules (should relations be loaded lazily? Should they be deleted if this object is deleted?).

Extbase models extend the TYPO3\CMS\Extbase\DomainObject\AbstractEntity class. The parent classes of this class already offer methods needed for persistence to database, the identifier uid etc.

Class TTN\Tea\Domain\Model\Product\Tea
use TYPO3\CMS\Extbase\Annotation\ORM\Lazy;
use TYPO3\CMS\Extbase\Domain\Model\FileReference;
use TYPO3\CMS\Extbase\Persistence\Generic\LazyLoadingProxy;

 * This class represents a tea (flavor), e.g., "Earl Grey".
class Tea extends AbstractEntity
    protected string $title = '';

    protected string $description = '';

     * @phpstan-var \TYPO3\CMS\Extbase\Domain\Model\FileReference|LazyLoadingProxy|null
     * @var \TYPO3\CMS\Extbase\Domain\Model\FileReference|null
     * @Lazy
    protected $image;


All properties of the model have to have the visibility keyword protected or public. private properties are not supported, as properties have to be accessed by the repository and persistence and layers internally.

If you want to prevent developers from extending you model, and accessing the properties of you model, you can make the class of the model final.

For all protected properties we need at least a getter with the corresponding name. If the property should be writable within Extbase, it must also have a getter. Properties that are only set in backend forms do not need a setter.

Example for the property title:

Class TTN\Tea\Domain\Model\Product\Tea
class Tea extends AbstractEntity
    protected string $title = '';

    public function getTitle(): string
        return $this->title;

    public function setTitle(string $title): void
        $this->title = $title;

The getter for the image also has to resolve the lazy loading:

Class TTN\Tea\Domain\Model\Product\Tea
use TYPO3\CMS\Extbase\Annotation\ORM\Lazy;
use TYPO3\CMS\Extbase\Domain\Model\FileReference;
use TYPO3\CMS\Extbase\Persistence\Generic\LazyLoadingProxy;

class Tea extends AbstractEntity
     * @phpstan-var \TYPO3\CMS\Extbase\Domain\Model\FileReference|LazyLoadingProxy|null
     * @var \TYPO3\CMS\Extbase\Domain\Model\FileReference|null
     * @Lazy
    protected $image;

    public function getImage(): ?FileReference
        if ($this->image instanceof LazyLoadingProxy) {
            /** @var FileReference $image */
            $image = $this->image->_loadRealInstance();
            $this->image = $image;

        return $this->image;

    public function setImage(FileReference $image): void
        $this->image = $image;

See the complete class on Github: Tea.

Next steps

  • The repository - Query for tea