Model: a bag of tea

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:

ctrl

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.

columns

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

types

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

EXT:tea/Configuration/TCA/tx_tea_domain_model_tea.php

[
    'ctrl' => [
        'title' => 'LLL:EXT:tea/Resources/Private/Language/locallang_db.xlf:tx_tea_domain_model_tea',
        'label' => 'title',
        'tstamp' => 'tstamp',
        'crdate' => 'crdate',
        'delete' => 'deleted',
        'default_sortby' => 'title',
        'iconfile' => 'EXT:tea/Resources/Public/Icons/Record.svg',
        'searchFields' => 'title, description',
        'enablecolumns' => [
            'fe_group' => 'fe_group',
            'disabled' => 'hidden',
            'starttime' => 'starttime',
            'endtime' => 'endtime',
        ],
        'transOrigPointerField' => 'l18n_parent',
        'transOrigDiffSourceField' => 'l18n_diffsource',
        'languageField' => 'sys_language_uid',
        'translationSource' => 'l10n_source',
    ],
]

Copied!

title

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.

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:

EXT:tea/Configuration/TCA/tx_tea_domain_model_tea.php

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

Copied!

label

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

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 Table properties (ctrl).

[
    'columns' => [
        'title' => [
            'label' => 'LLL:EXT:tea/Resources/Private/Language/locallang_db.xlf:tx_tea_domain_model_tea.title',
            'config' => [
                'type' => 'input',
                'size' => 40,
                'max' => 255,
                'eval' => 'trim',
                'required' => true,
            ],
        ],
    ],
]

<?php

return [
    // ...
    'columns' => [
        'image' => [
            'label' => 'LLL:EXT:tea/Resources/Private/Language/locallang_db.xlf:tx_tea_domain_model_tea.image',
            'type' => 'file',
            'maxitems' => 1,
            'appearance' => [
                'collapseAll' => true,
                'useSortable' => false,
                'enabledControls' => [
                    'hide' => false,
                ],
            ],
            'allowed' => 'common-image-types',
        ],
    ],
];

[
    'types' => [
        1 => [
            'showitem' => '--div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:general,
                    title, description, image, owner,
                 --div--;LLL:EXT:tea/Resources/Private/Language/locallang_db.xlf:tx_tea_domain_model_tea.tabs.access,
                    --palette--;;hidden,
                    --palette--;;access,',
        ],
    ],
]

Result - the complete TCA

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

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

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

Note

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.

use TYPO3\CMS\Extbase\Annotation as Extbase;
use TYPO3\CMS\Extbase\Domain\Model\FileReference;
use TYPO3\CMS\Extbase\DomainObject\AbstractEntity;
use TYPO3\CMS\Extbase\Persistence\Generic\LazyLoadingProxy;

/**
 * This class represents a tea (flavor), e.g., "Earl Grey".
 */
class Tea extends AbstractEntity
{
    /**
     * @Extbase\Validate("StringLength", options={"maximum": 255})
     * @Extbase\Validate("NotEmpty")
     */
    protected string $title = '';

    /**
     * @Extbase\Validate("StringLength", options={"maximum": 2000})
     */
    protected string $description = '';

    /**
     * @var FileReference|null
     * @phpstan-var FileReference|LazyLoadingProxy|null
     * @Extbase\ORM\Lazy
     */
    protected $image;
}

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 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:

use TYPO3\CMS\Extbase\Annotation as Extbase;
use TYPO3\CMS\Extbase\Domain\Model\FileReference;
use TYPO3\CMS\Extbase\DomainObject\AbstractEntity;
use TYPO3\CMS\Extbase\Persistence\Generic\LazyLoadingProxy;

class Tea extends AbstractEntity
{
    /**
     * @var FileReference|null
     * @phpstan-var FileReference|LazyLoadingProxy|null
     * @Extbase\ORM\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.