用途:指导在 TYPO3 v14 中通过 DataHandler 进行记录操作,遵循 TYPO3 API 优先原则,避免自造实现。
主要能力:使用 datamap($data[表][uid][字段]=值)创建或更新记录,新建记录用 NEW 开头的唯一字符串作 UID,并可在其他记录中引用该 NEW 标识;使用 cmdmaps($cmd[表][uid][命令]=值)执行删除、移动、复制、本地化等操作。DataHandler 会自动维护引用索引(sys_refindex)、清缓存、版本历史(sys_history)、工作区兼容、FlexForm 与 MM 关系,并接入核心定义的钩子/事件。
使用方式:通过 GeneralUtility::makeInstance(DataHandler::class) 获取实例(不要用 new,也不要依赖注入构造函数);先调用 start($dataMap, $commandMap[, $backendUser[, $referenceIndexUpdater]]),再调用 process_datamap() 和/或 process_cmdmap();随后检查 errorLog,用 substNEWwithIDs 获取新记录 UID,工作区中可查看 autoVersionIdMap。CLI/调度器场景需先 Bootstrap::initializeBackendAuthentication(),TYPO3 命令使用 cli 后端用户;需要其他用户时把 BackendUserAuthentication 作为 start() 第三个参数传入,不要手动设置 admin。缓存建议用 CacheManager、缓存组或 PSR-14 缓存事件。
限制:禁止对 pages、tt_content 及任何 TCA 配置表使用原生 SQL(INSERT/UPDATE/DELETE),例外包括无 TCA 的自定义日志表、只读批量分析查询、以及显式重建引用索引的迁移脚本。普通 DataHandler 写入会自动同步引用索引,通常无需手动调用 ReferenceIndex;v14 中 ReferenceIndex 与 updateRefIndexTable() 均为 @internal,扩展不应直接操作,优先使用 vendor/bin/typo3 referenceindex:update。官方文档未定义 DataHandler 的通用事务契约,普通扩展代码应先用基础 API,确需事务时须先验证数据库连接与副作用。start() 第 4 个参数为 @internal,扩展一般只用前 2 至 3 个参数。
适用场景:扩展中的内容创建/更新服务、导入命令、迁移与维护脚本、工作区相关记录操作。
暂未提供:具体收费、价格、平台支持范围与效果数据。