Guides transactional TYPO3 record manipulation with DataHandler, including datamaps, cmdmaps, backend user context, reference index handling, workspace-aware operations, hooks, and PSR-14 events. Use when creating, updating, moving, localizing, deleting, or extending TYPO3 records, pages, content, categories, IRRE children, or backend data operations.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
Instruções da origem · Visualização somente leitura
name
typo3-datahandler
description
Guides transactional TYPO3 record manipulation with DataHandler, including datamaps, cmdmaps, backend user context, reference index handling, workspace-aware operations, hooks, and PSR-14 events. Use when creating, updating, moving, localizing, deleting, or extending TYPO3 records, pages, content, categories, IRRE children, or backend data operations.
Compatibility: TYPO3 v14.x
All code examples in this skill are designed to work on TYPO3 v14.
TYPO3 API First: Always use TYPO3's built-in APIs, core features, and established conventions before creating custom implementations. Do not reinvent what TYPO3 already provides. Always verify that the APIs and methods you use exist and are not deprecated in TYPO3 v14 by checking the official TYPO3 documentation.
1. The Prime Directive
NEVER use raw SQL (, , ) for , , or any TCA-configured table.
INSERT
UPDATE
DELETE
pages
tt_content
You MUST use the DataHandler to ensure:
Reference Index updates (sys_refindex)
Cache clearing
Version history (sys_history)
Workspace compatibility
Correct hook/event integration where Core defines it (see §9)
FlexForm handling
MM relation management
Exceptions (Raw SQL Allowed)
Custom logging tables without TCA
Bulk analytics/reporting queries (read-only)
Migration scripts with explicit reference index rebuild
TYPO3's public DataHandler API for TYPO3 v14 is simply:
Obtain a DataHandler via GeneralUtility::makeInstance(DataHandler::class) per use — DataHandler holds state and must not be injected via dependency injection constructors; also avoid new DataHandler() so Core wiring (hooks, collaborators) stays consistent.
Call start($dataMap, $commandMap[, $backendUser[, $referenceIndexUpdater]])before any process_* call. The 4th parameter exists but is @internal; extension code should normally use only the first 2-3 arguments.
Call process_datamap() and / or process_cmdmap()
Inspect $dataHandler->errorLog, verify expected keys in $dataHandler->substNEWwithIDs for new records, and (in workspaces) review $dataHandler->autoVersionIdMap when you expect version rows.
Cache: Prefer CacheManager / cache groups or PSR-14 cache events instead of legacy DataHandler cache helpers.
The official docs do not define a general transaction contract for DataHandler. In normal extension code, use the plain API first and only add your own transaction handling after carefully validating the database connections and side effects involved in your specific use case.
For normal DataHandler writes, TYPO3 keeps the Reference Index in sync automatically. You usually do not need to call ReferenceIndex manually after ordinary process_datamap() / process_cmdmap() usage.
Manual Reference Index updates are primarily relevant for:
Deployments and TYPO3 upgrades
Changes to TCA-defined relations
Migrations or scripts that bypass DataHandler
Repair / maintenance scenarios
Rebuild the full Reference Index
vendor/bin/typo3 referenceindex:update
Update a specific record manually (discouraged)
In v14 both ReferenceIndex and updateRefIndexTable() are @internal — extensions shouldn't fiddle with the reference index themselves. Prefer vendor/bin/typo3 referenceindex:update or let DataHandler maintain the index. If you still call the internal API, expect it to change without deprecation:
<?phpdeclare(strict_types=1);
useTYPO3\CMS\Core\Database\ReferenceIndex;
useTYPO3\CMS\Core\Utility\GeneralUtility;
// @internal API — discouraged; prefer referenceindex:update or DataHandler$referenceIndex = GeneralUtility::makeInstance(ReferenceIndex::class);
$referenceIndex->updateRefIndexTable('tt_content', 123);
Detailed Reference
Read the full guide when the task needs detailed examples, long templates, troubleshooting matrices, appendices, or sections not included above. Keep this file unloaded for narrow tasks so the skill follows progressive disclosure.
