typo3-batch
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseTYPO3 Batch Operations
TYPO3 批量操作
Adapted from Boris Cherny's (Anthropic) Claude Codeskill for TYPO3 contexts. Target: TYPO3 v14 (primary), v13, v12.4 LTS./batch
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 Codeskill。 目标版本: 主要支持TYPO3 v14,同时兼容v13、v12.4 LTS。/batch
可对TYPO3代码库执行大规模、可并行的变更操作:将工作拆分为5-30个独立单元,提交计划供确认后逐个执行并验证。
Process
流程
- Research: Scan codebase to find all affected files
- Decompose: Split work into independent, non-conflicting units
- Plan: Present numbered plan to user for approval
- Execute: Apply each unit, run verification after each
- Report: Summarize changes, list any failures
- 调研:扫描代码库找出所有受影响的文件
- 拆分:将工作拆分为独立、无冲突的单元
- 规划:提交带编号的计划供用户审批
- 执行:应用每个单元的变更,每次执行后进行验证
- 报告:汇总变更内容,列出所有失败项
Execution Rules
执行规则
- Each unit must be independently verifiable
- Never modify the same file in two different units
- Run /
composer normalize/ PHPStan after PHP changesphp -l - 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/ PHPStan 检查php -l - 如果有测试用例则执行测试()
vendor/bin/phpunit - 每个单元单独提交并添加描述性提交信息
- 如果某个单元导致测试失败则停止执行并上报
Common TYPO3 Batch Operations
常见TYPO3批量操作
1. Hook → PSR-14 Event Migration
1. Hook 转 PSR-14 事件迁移
Research: Find all entries in and
.
$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']$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 fileHook → Event mapping (common):
| Hook | PSR-14 Event |
|---|---|
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
调研:查找和中的所有条目
$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 fileHook与事件映射(常见):
| Hook | PSR-14 事件 |
|---|---|
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
2. TCA Modernization (v12 → v14)
2. TCA 现代化(v12 → v14)
Research: Scan all and files.
Configuration/TCA/Configuration/TCA/Overrides/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 syntax3. GeneralUtility::makeInstance → DI
3. GeneralUtility::makeInstance 转 DI
Research: Find all calls in Classes/.
GeneralUtility::makeInstance()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 -l4. 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.sql6. ext_localconf / ext_tables Cleanup
6. ext_localconf / ext_tables 清理
Research: Scan and for movable code.
ext_localconf.phpext_tables.phpDecompose: 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.phpext_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.php7. Test Infrastructure Setup
7. 测试基础设施搭建
Research: Check if directory exists, find testable classes.
Tests/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调研:扫描目录下符合PHP 8.4迁移条件的代码
Classes/拆分:每个类文件对应一个执行单元
每个单元操作步骤:
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 syntax9. 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 frontend10. 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执行前向用户展示:
undefinedBatch Plan: [Description]
Batch Plan: [Description]
Target: EXT:my_extension (TYPO3 v14)
Files affected: 23
Units: 8
| # | Unit | Files | Risk |
|---|---|---|---|
| 1 | TCA/Overrides/tt_content.php | 1 | Low |
| 2 | TCA/Overrides/pages.php | 1 | Low |
| 3 | Classes/Controller/ListController.php | 1 | Medium |
| 4 | Classes/Service/ImportService.php | 1 | Medium |
| 5 | Resources/Private/Templates/ (6 files) | 6 | Low |
| 6 | ext_localconf.php → Configuration/ | 4 | Medium |
| 7 | Tests/Unit/ (new) | 5 | Low |
| 8 | locallang.xlf updates | 3 | Low |
Estimated: ~15 minutes
Proceed? [y/n]
undefinedTarget: EXT:my_extension (TYPO3 v14)
Files affected: 23
Units: 8
| # | Unit | Files | Risk |
|---|---|---|---|
| 1 | TCA/Overrides/tt_content.php | 1 | Low |
| 2 | TCA/Overrides/pages.php | 1 | Low |
| 3 | Classes/Controller/ListController.php | 1 | Medium |
| 4 | Classes/Service/ImportService.php | 1 | Medium |
| 5 | Resources/Private/Templates/ (6 files) | 6 | Low |
| 6 | ext_localconf.php → Configuration/ | 4 | Medium |
| 7 | Tests/Unit/ (new) | 5 | Low |
| 8 | locallang.xlf updates | 3 | Low |
Estimated: ~15 minutes
Proceed? [y/n]
undefinedVerification Checklist (per unit)
验证检查清单(每个单元)
- passes on all modified PHP files
php -l - passes (if composer.json touched)
composer normalize - 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 skill for TYPO3 contexts.
/batchCopyright (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内置 skill。
/batch版权所有 (c) Anthropic — 批量操作模式采用MIT许可证
感谢Netresearch DTT GmbH为TYPO3社区做出的贡献。