typo3-batch

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

TYPO3 Batch Operations

TYPO3 批量操作

Adapted from Boris Cherny's (Anthropic) Claude Code
/batch
skill for TYPO3 contexts. Target: TYPO3 v14 (primary), v13, v12.4 LTS.
Orchestrate large-scale, parallelizable changes across a TYPO3 codebase. Decompose work into 5–30 independent units, present a plan, then execute each unit with verification.
改编自Boris Cherny(Anthropic)为TYPO3场景适配的Claude Code
/batch
skill。 目标版本: 主要支持TYPO3 v14,同时兼容v13、v12.4 LTS。
可对TYPO3代码库执行大规模、可并行的变更操作:将工作拆分为5-30个独立单元,提交计划供确认后逐个执行并验证。

Process

流程

  1. Research: Scan codebase to find all affected files
  2. Decompose: Split work into independent, non-conflicting units
  3. Plan: Present numbered plan to user for approval
  4. Execute: Apply each unit, run verification after each
  5. Report: Summarize changes, list any failures
  1. 调研:扫描代码库找出所有受影响的文件
  2. 拆分:将工作拆分为独立、无冲突的单元
  3. 规划:提交带编号的计划供用户审批
  4. 执行:应用每个单元的变更,每次执行后进行验证
  5. 报告:汇总变更内容,列出所有失败项

Execution Rules

执行规则

  • Each unit must be independently verifiable
  • Never modify the same file in two different units
  • Run
    composer normalize
    /
    php -l
    / PHPStan after PHP changes
  • Run tests if available (
    vendor/bin/phpunit
    )
  • Commit each unit separately with descriptive message
  • Stop and report if a unit breaks tests
  • 每个单元必须可独立验证
  • 禁止在两个不同单元中修改同一个文件
  • PHP代码变更后需执行
    composer normalize
    /
    php -l
    / PHPStan 检查
  • 如果有测试用例则执行测试(
    vendor/bin/phpunit
  • 每个单元单独提交并添加描述性提交信息
  • 如果某个单元导致测试失败则停止执行并上报

Common TYPO3 Batch Operations

常见TYPO3批量操作

1. Hook → PSR-14 Event Migration

1. Hook 转 PSR-14 事件迁移

Research: Find all entries in
$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']
and
$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']
.
Decompose: One unit per hook class.
Per unit:
1. Identify the hook interface/method
2. Find the corresponding PSR-14 event (see mapping below)
3. Create new event listener class with #[AsEventListener]
4. Move logic from hook method to __invoke()
5. Remove hook registration from ext_localconf.php
6. Add Services.yaml entry (for v12/v13 fallback)
7. Run php -l on new file
Hook → Event mapping (common):
HookPSR-14 Event
processDatamap_afterDatabaseOperations
AfterRecordOperationEvent
processDatamap_preProcessFieldArray
BeforeRecordOperationEvent
processCmdmap_postProcess
AfterRecordOperationEvent
drawHeaderHook
ModifyButtonBarEvent
drawFooterHook
ModifyButtonBarEvent
checkFlexFormValue
AfterFlexFormDataStructureParsedEvent
pageRendererRender
BeforePageIsResolvedEvent
tslib_fe->contentPostProc
AfterCacheableContentIsGeneratedEvent
BackendUtility->getPagesTSconfig
ModifyLoadedPageTsConfigEvent
generatePageTSconfig
ModifyLoadedPageTsConfigEvent
调研:查找
$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']
$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']
中的所有条目
拆分:每个Hook类对应一个执行单元
每个单元操作步骤:
1. Identify the hook interface/method
2. Find the corresponding PSR-14 event (see mapping below)
3. Create new event listener class with #[AsEventListener]
4. Move logic from hook method to __invoke()
5. Remove hook registration from ext_localconf.php
6. Add Services.yaml entry (for v12/v13 fallback)
7. Run php -l on new file
Hook与事件映射(常见):
HookPSR-14 事件
processDatamap_afterDatabaseOperations
AfterRecordOperationEvent
processDatamap_preProcessFieldArray
BeforeRecordOperationEvent
processCmdmap_postProcess
AfterRecordOperationEvent
drawHeaderHook
ModifyButtonBarEvent
drawFooterHook
ModifyButtonBarEvent
checkFlexFormValue
AfterFlexFormDataStructureParsedEvent
pageRendererRender
BeforePageIsResolvedEvent
tslib_fe->contentPostProc
AfterCacheableContentIsGeneratedEvent
BackendUtility->getPagesTSconfig
ModifyLoadedPageTsConfigEvent
generatePageTSconfig
ModifyLoadedPageTsConfigEvent

2. TCA Modernization (v12 → v14)

2. TCA 现代化(v12 → v14)

Research: Scan all
Configuration/TCA/
and
Configuration/TCA/Overrides/
files.
Decompose: One unit per TCA file.
Per unit:
1. Replace 'eval' => 'required' → 'required' => true
2. Replace 'eval' => 'trim' → remove (default behavior)
3. Replace 'eval' => 'null' → 'nullable' => true
4. Replace 'eval' => 'int' → 'type' => 'number'
5. Replace 'renderType' => 'inputDateTime' → 'type' => 'datetime'
6. Replace 'renderType' => 'inputLink' → 'type' => 'link'
7. Replace 'renderType' => 'colorPicker' → 'type' => 'color'
8. Replace 'type' => 'input', 'eval' => 'email' → 'type' => 'email'
9. Convert items arrays: [0] => label, [1] => value → ['label' => ..., 'value' => ...]
10. Remove boilerplate columns auto-created from ctrl (v13.3+): hidden, starttime, endtime, fe_group, language fields
11. Use palettes for enablecolumns: visibility → hidden, access → starttime, endtime
12. Remove convention fields from ext_tables.sql (auto-added to database)
13. Run php -l to verify syntax
调研:扫描所有
Configuration/TCA/
Configuration/TCA/Overrides/
文件
拆分:每个TCA文件对应一个执行单元
每个单元操作步骤:
1. Replace 'eval' => 'required' → 'required' => true
2. Replace 'eval' => 'trim' → remove (default behavior)
3. Replace 'eval' => 'null' → 'nullable' => true
4. Replace 'eval' => 'int' → 'type' => 'number'
5. Replace 'renderType' => 'inputDateTime' → 'type' => 'datetime'
6. Replace 'renderType' => 'inputLink' → 'type' => 'link'
7. Replace 'renderType' => 'colorPicker' → 'type' => 'color'
8. Replace 'type' => 'input', 'eval' => 'email' → 'type' => 'email'
9. Convert items arrays: [0] => label, [1] => value → ['label' => ..., 'value' => ...]
10. Remove boilerplate columns auto-created from ctrl (v13.3+): hidden, starttime, endtime, fe_group, language fields
11. Use palettes for enablecolumns: visibility → hidden, access → starttime, endtime
12. Remove convention fields from ext_tables.sql (auto-added to database)
13. Run php -l to verify syntax

3. GeneralUtility::makeInstance → DI

3. GeneralUtility::makeInstance 转 DI

Research: Find all
GeneralUtility::makeInstance()
calls in Classes/.
Decompose: One unit per class file.
Per unit:
1. Identify all makeInstance calls in the class
2. For each: add constructor parameter with type
3. Replace makeInstance calls with $this->propertyName
4. Add/update Services.yaml if needed
5. Use readonly promoted properties
6. Verify with php -l
调研:查找
Classes/
目录下所有
GeneralUtility::makeInstance()
调用
拆分:每个类文件对应一个执行单元
每个单元操作步骤:
1. Identify all makeInstance calls in the class
2. For each: add constructor parameter with type
3. Replace makeInstance calls with $this->propertyName
4. Add/update Services.yaml if needed
5. Use readonly promoted properties
6. Verify with php -l

4. Fluid Template Refactoring

4. Fluid 模板重构

Research: Scan
Resources/Private/Templates/
,
Partials/
,
Layouts/
.
Decompose: One unit per template directory or logical group.
Per unit:
1. Replace hardcoded strings with <f:translate> keys
2. Add missing XLIFF entries to locallang.xlf
3. Replace <a href="..."> with <f:link.page> or <f:link.typolink>
4. Replace <img> with <f:image>
5. Extract repeated blocks to Partials
6. Add accessibility attributes (alt, aria-label, role)
调研:扫描
Resources/Private/Templates/
Partials/
Layouts/
目录
拆分:每个模板目录或逻辑组对应一个执行单元
每个单元操作步骤:
1. Replace hardcoded strings with <f:translate> keys
2. Add missing XLIFF entries to locallang.xlf
3. Replace <a href="..."> with <f:link.page> or <f:link.typolink>
4. Replace <img> with <f:image>
5. Extract repeated blocks to Partials
6. Add accessibility attributes (alt, aria-label, role)

5. Namespace Rename / Extension Key Change

5. 命名空间重命名/扩展键变更

Research: Find all files containing old namespace/extension key.
Decompose: Group by file type (PHP, Fluid, YAML, TypoScript, SQL).
Per unit:
PHP files:
  1. Replace namespace declarations
  2. Replace use statements
  3. Replace class references in strings (DI, TCA)
  
Fluid files:
  1. Replace {namespace} declarations
  2. Replace ViewHelper references
  
Configuration files:
  1. Update composer.json autoload
  2. Update ext_emconf.php
  3. Update Services.yaml service names
  4. Update TCA table prefixes
  5. Update TypoScript paths (EXT:old → EXT:new)
  
Database:
  1. Generate SQL rename migration
  2. Update ext_tables.sql
调研:查找所有包含旧命名空间/旧扩展键的文件
拆分:按文件类型分组(PHP、Fluid、YAML、TypoScript、SQL)
每个单元操作步骤:
PHP files:
  1. Replace namespace declarations
  2. Replace use statements
  3. Replace class references in strings (DI, TCA)
  
Fluid files:
  1. Replace {namespace} declarations
  2. Replace ViewHelper references
  
Configuration files:
  1. Update composer.json autoload
  2. Update ext_emconf.php
  3. Update Services.yaml service names
  4. Update TCA table prefixes
  5. Update TypoScript paths (EXT:old → EXT:new)
  
Database:
  1. Generate SQL rename migration
  2. Update ext_tables.sql

6. ext_localconf / ext_tables Cleanup

6. ext_localconf / ext_tables 清理

Research: Scan
ext_localconf.php
and
ext_tables.php
for movable code.
Decompose: One unit per concern (TSconfig, TypoScript, icons, modules, plugins).
Per unit:
Page TSconfig:
  1. Extract addPageTSConfig() calls
  2. Create Configuration/page.tsconfig
  3. Remove from ext_localconf.php

User TSconfig:
  1. Extract addUserTSConfig() calls  
  2. Create Configuration/user.tsconfig
  3. Remove from ext_localconf.php

Icons:
  1. Extract icon registry calls
  2. Move to Configuration/Icons.php (v14)
  3. Remove from ext_localconf.php

Backend modules:
  1. Extract registerModule() calls
  2. Move to Configuration/Backend/Modules.php
  3. Remove from ext_tables.php
调研:扫描
ext_localconf.php
ext_tables.php
中可迁移的代码
拆分:每个功能点对应一个执行单元(TSconfig、TypoScript、图标、模块、插件)
每个单元操作步骤:
Page TSconfig:
  1. Extract addPageTSConfig() calls
  2. Create Configuration/page.tsconfig
  3. Remove from ext_localconf.php

User TSconfig:
  1. Extract addUserTSConfig() calls  
  2. Create Configuration/user.tsconfig
  3. Remove from ext_localconf.php

Icons:
  1. Extract icon registry calls
  2. Move to Configuration/Icons.php (v14)
  3. Remove from ext_localconf.php

Backend modules:
  1. Extract registerModule() calls
  2. Move to Configuration/Backend/Modules.php
  3. Remove from ext_tables.php

7. Test Infrastructure Setup

7. 测试基础设施搭建

Research: Check if
Tests/
directory exists, find testable classes.
Decompose: One unit per test type.
Per unit:
Unit tests:
  1. Create Tests/Unit/ structure
  2. Generate test class per service/utility class
  3. Add phpunit.xml.dist configuration
  
Functional tests:
  1. Create Tests/Functional/ structure
  2. Add fixture files
  3. Generate test for repository/DataHandler usage

CI pipeline:
  1. Create .github/workflows/ci.yml
  2. Configure PHP matrix (8.2, 8.3, 8.4)
  3. Configure TYPO3 matrix (v13, v14)
调研:检查是否存在
Tests/
目录,查找可测试的类
拆分:每个测试类型对应一个执行单元
每个单元操作步骤:
Unit tests:
  1. Create Tests/Unit/ structure
  2. Generate test class per service/utility class
  3. Add phpunit.xml.dist configuration
  
Functional tests:
  1. Create Tests/Functional/ structure
  2. Add fixture files
  3. Generate test for repository/DataHandler usage

CI pipeline:
  1. Create .github/workflows/ci.yml
  2. Configure PHP matrix (8.2, 8.3, 8.4)
  3. Configure TYPO3 matrix (v13, v14)

8. PHP 8.4 Migration

8. PHP 8.4 迁移

Research: Scan Classes/ for PHP 8.4 migration candidates.
Decompose: One unit per class file.
Per unit:
1. Add property hooks where getter/setter pattern exists
2. Use asymmetric visibility (public private(set)) on DTOs
3. Replace array_search + if with array_find()
4. Replace array_filter + reset with array_find()
5. Replace manual array_key_exists checks with array_any/array_all
6. Add #[\Deprecated] attribute to legacy methods
7. Run php -l to verify syntax
调研:扫描
Classes/
目录下符合PHP 8.4迁移条件的代码
拆分:每个类文件对应一个执行单元
每个单元操作步骤:
1. Add property hooks where getter/setter pattern exists
2. Use asymmetric visibility (public private(set)) on DTOs
3. Replace array_search + if with array_find()
4. Replace array_filter + reset with array_find()
5. Replace manual array_key_exists checks with array_any/array_all
6. Add #[\Deprecated] attribute to legacy methods
7. Run php -l to verify syntax

9. Content Blocks Migration

9. 内容块迁移

Research: Scan TCA, ext_tables.sql, and Fluid templates for classic content elements.
Decompose: One unit per content element / record type.
Per unit:
1. Create ContentBlocks/ContentElements/<name>/config.yaml
2. Map TCA columns to YAML fields
3. Move Fluid template to ContentBlocks/ContentElements/<name>/Source/
4. Create EditorInterface.yaml
5. Remove old TCA override file
6. Remove SQL from ext_tables.sql (columns become automatic)
7. Test rendering in frontend
调研:扫描TCA、ext_tables.sql和Fluid模板中的传统内容元素
拆分:每个内容元素/记录类型对应一个执行单元
每个单元操作步骤:
1. Create ContentBlocks/ContentElements/<name>/config.yaml
2. Map TCA columns to YAML fields
3. Move Fluid template to ContentBlocks/ContentElements/<name>/Source/
4. Create EditorInterface.yaml
5. Remove old TCA override file
6. Remove SQL from ext_tables.sql (columns become automatic)
7. Test rendering in frontend

10. Localization / XLIFF Batch

10. 本地化/XLIFF 批量处理

Research: Find all hardcoded strings in Fluid, PHP flash messages, TCA labels.
Decompose: One unit per language file scope (frontend, backend, TCA).
Per unit:
1. Extract strings from templates/PHP
2. Generate XLIFF keys following convention
3. Add entries to Resources/Private/Language/locallang.xlf
4. Replace hardcoded strings with LLL: references
5. Create de.locallang.xlf with German translations (if applicable)
调研:查找Fluid、PHP flash消息、TCA标签中的所有硬编码字符串
拆分:每个语言文件作用域对应一个执行单元(前端、后端、TCA)
每个单元操作步骤:
1. Extract strings from templates/PHP
2. Generate XLIFF keys following convention
3. Add entries to Resources/Private/Language/locallang.xlf
4. Replace hardcoded strings with LLL: references
5. Create de.locallang.xlf with German translations (if applicable)

Plan Template

计划模板

Present to user before executing:
undefined
执行前向用户展示:
undefined

Batch Plan: [Description]

Batch Plan: [Description]

Target: EXT:my_extension (TYPO3 v14) Files affected: 23 Units: 8
#UnitFilesRisk
1TCA/Overrides/tt_content.php1Low
2TCA/Overrides/pages.php1Low
3Classes/Controller/ListController.php1Medium
4Classes/Service/ImportService.php1Medium
5Resources/Private/Templates/ (6 files)6Low
6ext_localconf.php → Configuration/4Medium
7Tests/Unit/ (new)5Low
8locallang.xlf updates3Low
Estimated: ~15 minutes
Proceed? [y/n]
undefined
Target: EXT:my_extension (TYPO3 v14) Files affected: 23 Units: 8
#UnitFilesRisk
1TCA/Overrides/tt_content.php1Low
2TCA/Overrides/pages.php1Low
3Classes/Controller/ListController.php1Medium
4Classes/Service/ImportService.php1Medium
5Resources/Private/Templates/ (6 files)6Low
6ext_localconf.php → Configuration/4Medium
7Tests/Unit/ (new)5Low
8locallang.xlf updates3Low
Estimated: ~15 minutes
Proceed? [y/n]
undefined

Verification Checklist (per unit)

验证检查清单(每个单元)

  • php -l
    passes on all modified PHP files
  • composer normalize
    passes (if composer.json touched)
  • PHPStan passes (if configured)
  • Unit tests pass (if available)
  • Functional tests pass (if available)
  • Frontend rendering unchanged (manual spot check)
  • Backend forms still work (manual spot check)
  • 所有修改的PHP文件
    php -l
    检查通过
  • 如果修改了composer.json则
    composer normalize
    检查通过
  • 如果配置了PHPStan则检查通过
  • 单元测试执行通过(如果有)
  • 功能测试执行通过(如果有)
  • 前端渲染无变更(手动抽查)
  • 后端表单可正常使用(手动抽查)

Abort Conditions

中止条件

Stop the batch and report if:
  • A unit breaks existing tests
  • PHP syntax error in generated code
  • Two units unexpectedly need the same file
  • User requests stop

出现以下情况时停止批量操作并上报:
  • 某个单元导致现有测试失败
  • 生成的代码存在PHP语法错误
  • 两个单元意外需要修改同一个文件
  • 用户请求停止

Credits & Attribution

鸣谢与归属

Adapted from Boris Cherny's (Anthropic) Claude Code bundled
/batch
skill for TYPO3 contexts.
Copyright (c) Anthropic — Batch operation patterns (MIT License)
Thanks to Netresearch DTT GmbH for their contributions to the TYPO3 community.
改编自Boris Cherny(Anthropic)为TYPO3场景适配的Claude Code内置
/batch
skill。
版权所有 (c) Anthropic — 批量操作模式采用MIT许可证
感谢Netresearch DTT GmbH为TYPO3社区做出的贡献。