# TYPO3 分数技能 Fractor 是一个通用文件重构工具，可以自动执行 TYPO3 升级的非 PHP 迁移。它通过迁移 FlexForms、TypoScript、Fluid 模板、YAML、Htaccess 文件和composer.json 来补充 [Rector]()（处理 PHP）。 > **TYPO3 API First：** 在创建自定义实现之前，始终使用 TYPO3 的内置 API、核心功能和既定约定。请务必通过检查官方 TYPO3 文档来验证您使用的 API 和方法是否存在，并且在您的目标 TYPO3 版本（v13 或 v14）中未弃用。 > **安全：** 切勿在生产环境中运行 Fractor。始终在具有版本控制的开发环境上运行。在发布之前检查并测试更改。 ## Fractor 与 Rector 工具|手柄|套餐 ---|---|--- **校长** | PHP 代码（类、TCA PHP、ext_localconf 等）| `ssch/typo3-rector` **分形** |非 PHP 文件（FlexForms、TypoScript、Fluid、YAML、Htaccess、composer.json）| `a9f/typo3-fractor` 一起使用两者来完成 TYPO3 升级。请参阅“typo3-extension-upgrade”技能了解完整的工作流程。 ## 1\.安装作曲家需要 a9f/typo3-fractor --dev 此元包安装所有 TYPO3 特定的文件处理器： * `a9f/fractor`（核心引擎） * `a9f/fractor-xml`（FlexForm/XML 处理） * `a9f/fractor-fluid`（流体模板处理） * `a9f/fractor-typoscript` （TypoScript/TSconfig 处理） * `a9f/fractor-yaml` （YAML 处理） * `a9f/fractor-htaccess` （Htaccess 处理） * `a9f/fractor-composer-json` (composer.json 处理) ## 2\.配置 ### 快速入门生成默认配置：供应商/bin/typo3-fractor-init ### 手动配置在项目根目录中创建 `fractor.php`： withPaths([ __DIR__ 。 '/包/', ]） ->withSets([ Typo3LevelSetList::UP_TO_TYPO3_13, ]); ### v14 的配置 withPaths([ __DIR__ 。 '/配置/', __DIR__ 。 '/资源/', ]） ->withSets([ Typo3LevelSetList::UP_TO_TYPO3_14, ]); ### 跳过规则或文件 withPaths([__DIR__ .'/packages/']) ->withSkip([ MigrateRequiredFlagFlexFormFractor::类， __DIR__ 。 '/packages/legacy_ext/', __DIR__ 。 '/packages/my_ext/Resources/Private/Templates/Old.html' => [ \a9f\Typo3Fractor\TYPO3v14\Fluid\ChangeLogoutHandlingInFeLoginFractor::类， ], ]） ->withSets([ Typo3LevelSetList::UP_TO_TYPO3_14, ]); ### 应用单一规则 withPaths([__DIR__ .'/packages/']) ->withRules([ MigrateItemsIndexedKeysToAssociativeFractor::class， ]); ## 3\.运行分数 ### 试运行（预览）供应商/bin/fractor 流程--dry-run ### 应用更改供应商/bin/fractor流程 ### 从集合中运行单个规则供应商/bin/fractor 进程 --only="a9f\Typo3Fractor\TYPO3v14\TypoScript\RemoveExternalOptionFromTypoScriptFractor" ### 与 DDEV ddev exec 供应商/bin/fractor 进程 --dry-run ddev exec 供应商/bin/fractor 进程 ## 4\.可用曲目列表 ### 级别集（累积）应用所有规则直至目标版本：设置列表|包括 ---|--- `Typo3LevelSetList::UP_TO_TYPO3_10` | v7 + v8 + v10 `Typo3LevelSetList::UP_TO_TYPO3_11` | ... + v11 `Typo3LevelSetList::UP_TO_TYPO3_12` | ... + v12 `Typo3LevelSetList::UP_TO_TYPO3_13` | ... + v13 `Typo3LevelSetList::UP_TO_TYPO3_14` | ... + v14 ### 版本特定集仅对单个版本应用规则：设置列表|描述 ---|--- `Typo3SetList::TYPO3_12` |仅限 v12 规则 `Typo3SetList::TYPO3_13` |仅限 v13 规则 `Typo3SetList::TYPO3_14` |仅限 v14 规则 ## 5\.按文件类型和版本划分的规则 ### FlexForm 规则 (v12) 规则|迁移 ---|--- `MigrateEmailFlagToEmailTypeFlexFormFractor` | `eval=电子邮件` → `类型=电子邮件` `MigrateEvalIntAndDouble2ToTypeNumberFlexFormFractor` | `eval=int/double2` → `类型=数字` `MigrateInternalTypeFolderToTypeFolderFlexFormFractor` | `internalType=文件夹` → `类型=文件夹` `MigrateItemsIndexedKeysToAssociativeFractor` |索引项 → `label`/`value` 键 `MigrateNullFlagFlexFormFractor` | `eval=null` → `nullable=true` `MigratePasswordAndSaltedPasswordToPasswordTypeFlexFormFractor` |密码评估 → `type=password` `MigrateRenderTypeColorpickerToTypeColorFlexFormFractor` | `renderType=colorPicker` → `type=color` `MigrateRequiredFlagFlexFormFractor` | `eval=required` → `required=1` `MigrateTypeNoneColsToSizeFlexFormFractor` | `cols` → `size` for type=none `RemoveTceFormsDomElementFlexFormFractor` |删除``包装器 ### TypoScript 规则 (v12) 规则|迁移 ---|--- `MigrateTypoScriptLoginUserAndUsergroupConditionsFractor` |旧条件 → Symfony 表达式 `RemoveConfigDisablePageExternalUrlFractor` |删除`config.disablePageExternalUrl` `RemoveConfigDoctypeSwitchFractor` |删除`config.doctypeSwitch` `RemoveConfigMetaCharsetFractor` |删除`config.metaCharset` `RemoveConfigSendCacheHeadersOnlyWhenLoginDeniedInBranchFractor` |删除已弃用的缓存标头配置 `RemoveConfigSpamProtectEmailAddressesAsciiOptionFractor` |删除“ascii”选项 `RemoveNewContentElementWizardOptionsFractor` |删除旧版 CE 向导 TSconfig `删除工作空间模式选项分数` |删除工作区模式选项 `RenameConfigXhtmlDoctypeToDoctypeFractor` | `xhtmlDoctype` → `doctype` `重命名TcemainLinkHandlerMailKeyFractor` |重命名邮件链接处理程序键 `UseConfigArrayForTSFEPropertiesFractor` | TSFE 属性 → 配置数组 ### 流体规则 (v12) 规则|迁移 ---|--- `AbstractMessageGetSeverityFluidFractor` |迁移 Fluid 中的严重性常量 ### TypoScript 规则 (v13) 规则|迁移 ---|--- `MigrateIncludeTypoScriptSyntaxFractor` | `withPaths([__DIR__ .'/配置/']) ->withOptions([ TypoScriptProcessorOption::INDENT_SIZE => 2, TypoScriptProcessorOption::INDENT_CHARACTER => PrettyPrinterConfiguration::INDENTATION_STYLE_SPACES， TypoScriptProcessorOption::ADD_CLOSING_GLOBAL => false, TypoScriptProcessorOption::INCLUDE_EMPTY_LINE_BREAKS => true, TypoScriptProcessorOption::INDENT_CONDITIONS => true, TypoScriptProcessorOption::CONDITION_TERMINATION => PrettyPrinterConditionTermination::保留， ]); **缩进字符选项：** * `PrettyPrinterConfiguration::INDENTATION_STYLE_SPACES` \-- 使用空格 * `PrettyPrinterConfiguration::INDENTATION_STYLE_TABS` \-- 使用制表符 * `'auto'` \-- 从文件中检测并保持现有 **条件终止选项：** * `PrettyPrinterConditionTermination::Keep` \-- 保持现有 * `PrettyPrinterConditionTermination::EnforceGlobal` \-- 始终为 `[global]` * `PrettyPrinterConditionTermination::EnforceEnd` \-- 总是 `[end]` ### XML/FlexForm 格式 withPaths([__DIR__ .'/配置/']) ->withOptions([ XmlProcessorOption::INDENT_CHARACTER => 缩进::STYLE_TAB， XmlProcessorOption::INDENT_SIZE => 1, ]); ### 文件扩展名过滤控制每个处理器处理哪些文件扩展名： withPaths([__DIR__ .'/packages/']) ->withOptions([ FluidProcessorOption::ALLOWED_FILE_EXTENSIONS => ['html'], TypoScriptProcessorOption::ALLOWED_FILE_EXTENSIONS => ['typoscript', 'tsconfig'], XmlProcessorOption::ALLOWED_FILE_EXTENSIONS => ['xml', 'xlf'], YamlProcessorOption::ALLOWED_FILE_EXTENSIONS => ['yaml', 'yml'], ]); **默认扩展名：** * 流体：`html`、`xml`、`txt` * TypoScript：`typoscript`、`tsconfig`、`ts` * XML：`xml` * YAML：`yaml`，`yml` ## 7\.编写自定义规则 ### 自定义 XML/FlexForm 规则基于 XML 的规则的子类 `\a9f\FractorXml\XmlFractor`： nodeName === 'config' && $node->parentNode?->nodeName === 'TCEforms'; } 公共函数重构(DOMNode $node): DOMNode|int|null { // 修改DOM节点返回$节点； } 公共函数 getDescription(): 字符串 { return '迁移自定义 FlexForm 配置'; } } ### 注册自定义规则 withPaths([__DIR__ .'/packages/']) ->withRules([ MyCustomFlexFormFractor::类， ]); ## 8\.升级工作流程集成 ### 推荐顺序 1. git checkout -b 功能/typo3-upgrade 2.运行Rector（PHP迁移）→vendor/bin/rector进程 3.运行Fractor（非PHP迁移）→vendor/bin/fractor进程 4.运行PHP-CS-Fixer（代码风格）→vendor/bin/php-cs-fixer修复 5.运行PHPStan（静态分析）→vendor/bin/phpstan分析 6. 运行测试→vendor/bin/phpunit 7. 目标版本手动测试 ### 组合 fractor.php 用于扩展开发 withPaths([ __DIR__ 。 '/配置/', __DIR__ 。 '/资源/', ]） ->withSkip([ __DIR__ 。 '/资源/公共/', ]） ->withSets([ Typo3LevelSetList::UP_TO_TYPO3_13, ]） ->withOptions([ TypoScriptProcessorOption::INDENT_SIZE => 4, TypoScriptProcessorOption::INDENT_CHARACTER => PrettyPrinterConfiguration::INDENTATION_STYLE_SPACES， ]); ## 9\.故障排除 ### Fractor 无法解析 TypoScript # 首先检查 TypoScript 中的语法错误 # Fractor 使用 helmich/typo3-typoscript-parser ，它需要有效的 TypoScript # 跳过有问题的文件供应商/bin/fractor 流程--dry-run # 然后将它们添加到 fractor.php 中的 withSkip() 中 ### FlexForm 更改未应用 # 确保 XML 文件位于配置的路径中 # 检查 ALLOWED_FILE_EXTENSIONS 是否包含“xml” # 验证 FlexForm 具有预期的结构 () ### 意外的格式更改 # 在fractor.php中显式配置代码风格 # 使用“自动”缩进检测来保留现有格式 # 查看 withOptions() 设置 ### 在 CI 中运行 Fractor # .github/workflows/fractor.yml - 名称：检查分数运行：vendor/bin/fractor process --dry-run # 如果任何规则适用则失败 = 过时的代码 ## 10\.资源 * **Fractor 存储库**： * **TYPO3 Fractor 包**： * **Packagist** ： * **TYPO3 Rector**（PHP 伴侣）： * **相关技能**：`typo3-extension-upgrade`（完整升级工作流程），`typo3-rector`（PHP 迁移） ** ** ## 制作人员及归属感谢 [Andreas Wolf]() 创建和维护 Fractor。感谢 Netresearch DTT GmbH 对 TYPO3 社区的贡献。

Typo3 分数

包含技能