TYPO3 DataHandler Skill

Expert patterns for working with TYPO3's DataHandler (formerly TCEmain) - the central API for all database record operations in the TYPO3 backend.

What is DataHandler?

The DataHandler (\TYPO3\CMS\Core\DataHandling\DataHandler) is TYPO3's core class for:

• Creating new records in any TCA-configured table
• Updating existing records
• Copying records (with optional child elements)
• Moving records between pages
• Deleting/Undeleting records (soft delete)
• Localizing records for multilingual sites
• Versioning and Workspaces (staging, publishing, approval workflows)
• Cache clearing operations

All operations respect TCA configuration, user permissions, and workspace states.

Workspaces Overview

Workspaces allow staging changes before publishing:

• Live workspace (id = 0): Published content visible to visitors
• Custom workspaces (id > 0): Staging areas for draft changes
• DataHandler automatically creates versions when editing in a workspace
• Use version command for publish/swap/discard operations

Quick Reference

Basic Usage Pattern

<?php
declare(strict_types=1);

use TYPO3\CMS\Core\DataHandling\DataHandler;
use TYPO3\CMS\Core\Utility\GeneralUtility;

// NEVER inject DataHandler - always create new instance
$dataHandler = GeneralUtility::makeInstance(DataHandler::class);
$dataHandler->start($data, $cmd);
$dataHandler->process_datamap();  // For data operations
$dataHandler->process_cmdmap();   // For command operations

// Check for errors
if ($dataHandler->errorLog !== []) {
    foreach ($dataHandler->errorLog as $error) {
        // Handle error
    }
}

Data Array Syntax (Create/Update)

// Create new record (use NEW + unique ID)
$data['pages']['NEW123'] = [
    'pid' => 1,           // Parent page ID
    'title' => 'My Page',
    'hidden' => 0,
];

// Update existing record
$data['tt_content'][42] = [
    'header' => 'Updated Header',
    'bodytext' => 'New content',
];

// Reference NEW record in another NEW record
$data['sys_category']['NEW_cat'] = ['title' => 'New Category', 'pid' => 1];
$data['tt_content']['NEW_content'] = [
    'pid' => 1,
    'categories' => 'NEW_cat',  // References the category above
];

Command Array Syntax (Copy/Move/Delete)

// Delete record
$cmd['tt_content'][42]['delete'] = 1;

// Undelete record
$cmd['tt_content'][42]['undelete'] = 1;

// Copy to page (positive = first in page)
$cmd['tt_content'][42]['copy'] = 10;

// Copy after record (negative = after that UID)
$cmd['tt_content'][42]['copy'] = -55;

// Move to page
$cmd['tt_content'][42]['move'] = 10;

// Localize to language
$cmd['tt_content'][42]['localize'] = 2;  // Language UID

// Copy to language (free mode, no parent reference)
$cmd['tt_content'][42]['copyToLanguage'] = 2;

Expertise Areas

Data Operations (process_datamap())

• Record creation with NEW placeholders
• Record updates with field values
• Inline (IRRE) record handling
• FlexForm data submission
• File references (FAL)
• MM relation handling

Command Operations (process_cmdmap())

• copy - Duplicate records with children
• move - Relocate records
• delete - Soft delete (respects TCA delete field)
• undelete - Restore deleted records
• localize - Create language overlays (connected mode)
• copyToLanguage - Copy to language (free mode)
• version - Workspace operations

Getting Created Record UIDs

// After process_datamap(), get the real UID
$realUid = $dataHandler->substNEWwithIDs['NEW123'];

// For copied records
$dataHandler->copyMappingArray_merged['tt_content'][42]; // Returns new UID

Cache Operations

$dataHandler->start([], []);
$dataHandler->clear_cacheCmd('pages');    // Clear all page cache
$dataHandler->clear_cacheCmd('all');      // Clear all caches (admin only)
$dataHandler->clear_cacheCmd(123);        // Clear specific page cache

Reference Files

• references/data-array.md - Data array patterns and examples
• references/command-array.md - Command operations reference
• references/workspaces.md - Workspaces, versioning, staging, publishing
• references/hooks-events.md - Hook into DataHandler operations
• references/common-patterns.md - Typical use cases and solutions

Critical Rules

⚠️ NEVER Inject DataHandler

// ❌ WRONG - DataHandler is stateful
public function __construct(private DataHandler $dataHandler) {}

// ✅ CORRECT - Always create new instance
$dataHandler = GeneralUtility::makeInstance(DataHandler::class);

⚠️ Backend Context Required

DataHandler requires $GLOBALS['BE_USER']. In CLI commands:

\TYPO3\CMS\Core\Core\Bootstrap::initializeBackendAuthentication();

⚠️ TCA Configuration Required

Fields must be configured in TCA to be processed. If type is none or invalid, DataHandler ignores the field.

⚠️ sys_file Table Blocked

Direct modifications to sys_file are blocked since TYPO3 11.5.35/12.4.11/13.0.1 for security.

Common Patterns

Create Page with Content

$data = [
    'pages' => [
        'NEW_page' => [
            'pid' => 1,
            'title' => 'New Page',
            'doktype' => 1,
        ],
    ],
    'tt_content' => [
        'NEW_content' => [
            'pid' => 'NEW_page',  // Reference to new page
            'CType' => 'text',
            'header' => 'Welcome',
            'bodytext' => 'Content here',
        ],
    ],
];

$dataHandler = GeneralUtility::makeInstance(DataHandler::class);
$dataHandler->start($data, []);
$dataHandler->process_datamap();

$pageUid = $dataHandler->substNEWwithIDs['NEW_page'];
$contentUid = $dataHandler->substNEWwithIDs['NEW_content'];

Bulk Operations with Ordering

// Create multiple records in correct order
$data = [
    'pages' => [
        'NEW_1' => ['pid' => 1, 'title' => 'Page 1'],
        'NEW_2' => ['pid' => 1, 'title' => 'Page 2'],
    ],
];

$dataHandler = GeneralUtility::makeInstance(DataHandler::class);
$dataHandler->reverseOrder = true;  // Preserve array order
$dataHandler->start($data, []);
$dataHandler->process_datamap();

Copy Record with Modifications

$cmd = [
    'tt_content' => [
        42 => [
            'copy' => [
                'action' => 'paste',
                'target' => 10,  // Page UID
                'update' => [
                    'header' => 'Copied: ' . $originalHeader,
                ],
            ],
        ],
    ],
];

Workspace Operations

// Publish (swap) a workspace version
$cmd['pages'][42]['version'] = [
    'action' => 'swap',
    'swapWith' => 123,  // Workspace version UID
];

// Discard workspace changes
$cmd['pages'][42]['version'] = [
    'action' => 'clearWSID',
];

// Set approval stage
$cmd['pages'][42]['version'] = [
    'action' => 'setStage',
    'stageId' => 10,  // -1=rejected, 0=editing, 1=review, 10=publish
    'comment' => 'Ready for review',
];

// Bypass workspace restrictions (use carefully!)
$dataHandler->bypassWorkspaceRestrictions = true;

See references/workspaces.md for complete workspace patterns.

Hooking Into DataHandler

Legacy Hooks (still supported)

// ext_localconf.php
$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['t3lib/class.t3lib_tcemain.php']['processDatamapClass'][]
    = \MyVendor\MyExt\Hook\DataHandlerHook::class;

$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['t3lib/class.t3lib_tcemain.php']['processCmdmapClass'][]
    = \MyVendor\MyExt\Hook\DataHandlerHook::class;

Hook Methods

class DataHandlerHook
{
    // Before record is saved
    public function processDatamap_preProcessFieldArray(
        array &$fieldArray,
        string $table,
        string|int $id,
        DataHandler $dataHandler
    ): void {}

    // After record is saved
    public function processDatamap_postProcessFieldArray(
        string $status,  // 'new' or 'update'
        string $table,
        string|int $id,
        array $fieldArray,
        DataHandler $dataHandler
    ): void {}

    // After all records processed
    public function processDatamap_afterAllOperations(DataHandler $dataHandler): void {}

    // Before command executed
    public function processCmdmap_preProcess(
        string $command,
        string $table,
        int $id,
        mixed $value,
        DataHandler $dataHandler,
        bool|string $pasteUpdate
    ): void {}

    // After command executed
    public function processCmdmap_postProcess(
        string $command,
        string $table,
        int $id,
        mixed $value,
        DataHandler $dataHandler,
        bool|string $pasteUpdate,
        bool|string $pasteDatamap
    ): void {}
}

Error Handling

$dataHandler = GeneralUtility::makeInstance(DataHandler::class);
$dataHandler->start($data, $cmd);
$dataHandler->process_datamap();
$dataHandler->process_cmdmap();

if ($dataHandler->errorLog !== []) {
    foreach ($dataHandler->errorLog as $error) {
        $this->logger->error('DataHandler error', ['message' => $error]);
    }
}

Verification Checklist

Before using DataHandler:

• TCA is properly configured for all tables/fields
• Backend user context exists ($GLOBALS['BE_USER'])
• User has permissions for the operation
• Creating new instance (not injecting)
• Checking errorLog after operations
• Using substNEWwithIDs to get created record UIDs

Documentation: TYPO3 DataHandler Reference