Columns 

Visibility modes 

TCA_API has two visibility modes. The mode is auto-detected per resource:

Default mode

Active when no column has groups set. All non-system TCA columns (i.e. not hidden, deleted, tstamp, crdate, language/workspace fields) are automatically exposed for read and write.

Explicit mode

Active as soon as any column declares groups. Only columns with a matching groups entry are exposed; all others are hidden.

Serialization groups 

Use groups to control visibility per operation:

'columns' => [
    'title'  => ['groups' => ['list', 'show', 'create', 'update']],  // everywhere
    'teaser' => ['groups' => ['list']],                              // list only
    'body'   => ['groups' => ['show']],                              // detail view only
    'secret' => ['groups' => []],                                    // never exposed
],

Valid group names: list, show, create, update.

Column options reference 

All keys are optional.

Field type support 

The serializer automatically handles all TYPO3 TCA field types. Relational types are resolved via dedicated serializers; scalar types that store encoded data are decoded before output; sensitive types are excluded entirely.

An explicit processor on a column definition always overrides the automatic handling described above.

Column processors 

Column processors transform values during serialization. The extension ships two built-in processors:

FileProcessor

Serialises file references (FAL). Useful for file download columns.

use MaikSchneider\TcaApi\Serializer\FileProcessing\FileProcessor;

'downloads' => [
    'groups'    => ['list', 'show'],
    'processor' => FileProcessor::class,
],

Copied!

TypoLinkProcessor

Resolves TYPO3 typolinks to full URLs.

use MaikSchneider\TcaApi\Serializer\Processing\TypoLinkProcessor;

'article_url' => [
    'groups'    => ['list', 'show'],
    'processor' => TypoLinkProcessor::class,
],

Copied!

ImageProcessor

Serialises image file references (FAL) with full crop-variant support and configurable processing options. By default the processor is used for every type=file TCA column that has no explicit processor key.

Options are controlled via the image sub-key on the column definition:

use MaikSchneider\TcaApi\Serializer\FileProcessing\ImageProcessor;

'hero_image' => [
    'groups'    => ['list', 'show'],
    'processor' => ImageProcessor::class,  // optional — also the default for type=file
    'image'     => [
        'maxWidth'      => 1200,
        'maxHeight'     => 800,
        'fileExtension' => 'webp',
        // omit cropVariant → all variants returned as a map
    ],
],

Copied!

Output mode 1 — all variants (cropVariant omitted or null):

Every crop variant stored on the file reference is processed and returned as a cropVariants map:

{
    "hero_image": {
        "publicUrl": "/fileadmin/hero.jpg",
        "mimeType": "image/jpeg",
        "fileSize": 204800,
        "metadata": {
            "title": "Hero",
            "alternative": "A hero image",
            "description": null,
            "copyright": "© 2026"
        },
        "cropVariants": {
            "default": {
                "publicUrl": "/fileadmin/_processed_/hero_c.webp",
                "width": 1024,
                "height": 512
            },
            "mobile": {
                "publicUrl": "/fileadmin/_processed_/hero_m.webp",
                "width": 375,
                "height": 200
            }
        }
    }
}

Copied!

Output mode 2 — single variant (cropVariant set to a variant ID):

Only that variant is processed and the result is inlined as the top-level image — no cropVariants key:

'hero_image' => [
    'groups' => ['list', 'show'],
    'image'  => [
        'maxWidth'    => 1200,
        'cropVariant' => 'default',    // single-variant mode
    ],
],

Copied!

{
    "hero_image": {
        "publicUrl": "/fileadmin/_processed_/hero_c.webp",
        "width": 1200,
        "height": 600,
        "mimeType": "image/jpeg",
        "fileSize": 204800,
        "metadata": { "title": "Hero", "alternative": null, "description": null, "copyright": null }
    }
}

Copied!

Key	Type	Description
width	string	Target width. Accepts a plain integer ("400"), crop-scale ("400c"), or scale-down-only ("400m"). Mutually usable with maxWidth.
height	string	Target height — same notation as width.
minWidth	int	Minimum width in pixels. Must be a positive integer.
minHeight	int	Minimum height in pixels. Must be a positive integer.
maxWidth	int	Maximum width in pixels. Must be a positive integer.
maxHeight	int	Maximum height in pixels. Must be a positive integer.
cropVariant	string	Crop variant identifier (e.g. 'default', 'mobile'). When set, only that variant is processed and the URL is returned as top-level publicUrl (no cropVariants key). When omitted, all variants are returned as a cropVariants map.
fileExtension	string	Target file extension for format conversion, e.g. 'webp'.
absolute	bool	Force an absolute URL. Default: false.

Custom processors must implement \MaikSchneider\TcaApi\Serializer\Processing\ColumnProcessorInterface.