Creates, updates, moves, localizes and deletes TYPO3 records programmatically from PHP - import scripts, CLI commands, data migrations - using DataHandler datamaps and cmdmaps. Use when writing hundreds of pages or records from JSON, CSV or another system and the parent references must stay intact, when the reference index goes stale after moving records, when imported records show up owned by nobody because the backend user context is wrong, when localizing an existing element into another language from code, or when extending record operations with hooks and PSR-14 events. Workspace-aware.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Creates, updates, moves, localizes and deletes TYPO3 records programmatically from PHP - import scripts, CLI commands, data migrations - using DataHandler datamaps and cmdmaps. Use when writing hundreds of pages or records from JSON, CSV or another system and the parent references must stay intact, when the reference index goes stale after moving records, when imported records show up owned by nobody because the backend user context is wrong, when localizing an existing element into another language from code, or when extending record operations with hooks and PSR-14 events. Workspace-aware.
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 (INSERT, UPDATE, DELETE) for pages, tt_content, or any TCA-configured table.
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.
