typo3-fractor

TYPO3 Fractor 技能

来源：https://github.com/dirnbauer/webconsulting-skills

Fractor 是一款通用文件重构工具，可自动处理 TYPO3 升级中的非 PHP 迁移。它与 Rector（负责处理 PHP）相辅相成，可迁移 FlexForms、TypoScript、Fluid 模板、YAML、XLIFF 翻译文件、Htaccess 文件和 composer.json。Fractor 自 v1.0（2026 年 7 月）起已稳定；由 Simon Schaufelberger 和 Andreas Wolf 维护，并部分由 TYPO3 社区预算资助。

目标版本：此技能集合面向 TYPO3 v14.x。上游 Fractor 规则集的名称可能仍为 TYPO3_12、TYPO3_13 等——这些是历史规则包标识符，用于将代码迁移至 v14 代码库。

**优先使用 TYPO3 API：**始终先使用 TYPO3 内置 API、核心功能和既有约定，再创建自定义实现。务必查阅 TYPO3 官方文档，确认所用 API 和方法在 TYPO3 v14 中存在且未被弃用。

**安全提示：**切勿在生产环境运行 Fractor。始终在启用了版本控制的开发环境中运行。发布前请检查并测试更改。

Fractor 与 Rector

工具	处理内容	软件包
Rector	PHP 代码（类、TCA PHP、ext_localconf 等）	ssch/typo3-rector
Fractor	非 PHP 文件（FlexForms、TypoScript、Fluid、YAML、Htaccess、composer.json）	a9f/typo3-fractor

两者配合使用，完成完整的 TYPO3 升级。完整工作流请参阅 typo3-extension-upgrade 技能。

1. 安装

composer require --dev a9f/typo3-fractor
# or with DDEV:
ddev composer require --dev a9f/typo3-fractor

**重要提示：**与 Rector 一样，Fractor 会加载项目自动加载器，并要求 PHP 版本能够解析已安装的 TYPO3 软件包。 对于目标为 TYPO3 v14 的项目，请使用 PHP 8.2 或更高版本运行 Fractor。如果本机 PHP 版本较低，请使用 DDEV 或容器。

**务必运行 Fractor，切勿跳过。**非 PHP 文件（FlexForms、TypoScript、Fluid）中包含特定版本的模式，人工审查时很容易遗漏。Fractor 规则由 TYPO3 社区维护，可覆盖边缘情况。

此元软件包会安装所有 TYPO3 专用文件处理器（截至 Fractor v1.0 的规则集）：

• a9f/fractor（核心引擎）
• a9f/fractor-extension-installer（自动注册处理器）
• a9f/fractor-xml（FlexForm/XML 处理）
• a9f/fractor-fluid（Fluid 模板处理）
• a9f/fractor-typoscript（TypoScript/TSconfig 处理）
• a9f/fractor-yaml（YAML 处理）
• a9f/fractor-htaccess（Htaccess 处理）
• a9f/fractor-xliff（XLIFF 翻译文件处理——v1.0 新增；与 typo3-translations 技能搭配使用）
• a9f/fractor-composer-json（composer.json 处理——仍未包含在元软件包中；需要时请运行 composer require --dev a9f/fractor-composer-json 添加）

2. 配置

快速开始

生成默认配置：

vendor/bin/typo3-fractor-init

手动配置

在项目根目录创建 fractor.php：

<?php
declare(strict_types=1);

use a9f\Fractor\Configuration\FractorConfiguration;
use a9f\Typo3Fractor\Set\Typo3LevelSetList;

return FractorConfiguration::configure()
    ->withPaths([
        __DIR__ . '/packages/',
    ])
    ->withSets([
        Typo3LevelSetList::UP_TO_TYPO3_14,
    ]);

v14 配置

<?php
declare(strict_types=1);

use a9f\Fractor\Configuration\FractorConfiguration;
use a9f\Typo3Fractor\Set\Typo3LevelSetList;

return FractorConfiguration::configure()
    ->withPaths([
        __DIR__ . '/Configuration/',
        __DIR__ . '/Resources/',
    ])
    ->withSets([
        Typo3LevelSetList::UP_TO_TYPO3_14,
    ]);

跳过规则或文件

<?php
declare(strict_types=1);

use a9f\Fractor\Configuration\FractorConfiguration;
use a9f\Typo3Fractor\Set\Typo3LevelSetList;
use a9f\Typo3Fractor\TYPO3v12\FlexForm\MigrateRequiredFlagFlexFormFractor;

return FractorConfiguration::configure()
    ->withPaths([__DIR__ . '/packages/'])
    ->withSkip([
        MigrateRequiredFlagFlexFormFractor::class,
        __DIR__ . '/packages/legacy_ext/',
        __DIR__ . '/packages/my_ext/Resources/Private/Templates/Old.html' => [
            \a9f\Typo3Fractor\TYPO3v14\Fluid\ChangeLogoutHandlingInFeLoginFractor::class,
        ],
    ])
    ->withSets([
        Typo3LevelSetList::UP_TO_TYPO3_14,
    ]);

应用单条规则

<?php
declare(strict_types=1);

use a9f\Fractor\Configuration\FractorConfiguration;
use a9f\Typo3Fractor\TYPO3v12\FlexForm\MigrateItemsIndexedKeysToAssociativeFractor;

return FractorConfiguration::configure()
    ->withPaths([__DIR__ . '/packages/'])
    ->withRules([
        MigrateItemsIndexedKeysToAssociativeFractor::class,
    ]);

3. 运行 Fractor

试运行（预览）

vendor/bin/fractor process --dry-run

应用更改

vendor/bin/fractor process

常用 CLI 选项（v1.0 起）

vendor/bin/fractor process --dry-run --no-diffs        # summary without diff output
vendor/bin/fractor process --dry-run --rules-summary   # which rules changed which files
vendor/bin/fractor process --memory-limit=2G           # raise the limit for large projects

**v1.0 中的破坏性变更：**CLI 选项 --quiet 已移除。

运行规则集中的单条规则

vendor/bin/fractor process --only="a9f\Typo3Fractor\TYPO3v14\TypoScript\RemoveExternalOptionFromTypoScriptFractor"

使用 DDEV

ddev exec vendor/bin/fractor process --dry-run
ddev exec vendor/bin/fractor process

4. 可用规则集列表

等级规则集（累积）

应用截至目标版本的所有规则：

规则集列表	包含内容
Typo3LevelSetList::UP_TO_TYPO3_10	导入 UP_TO_TYPO3_9，并仅包含 TYPO3_10 规则（参见软件包中的 config/level/up-to-typo3-10.php）
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=email → type=email
MigrateEvalIntAndDouble2ToTypeNumberFlexFormFractor	eval=int/double2 → type=number
MigrateInternalTypeFolderToTypeFolderFlexFormFractor	internalType=folder → type=folder
MigrateItemsIndexedKeysToAssociativeFractor	将索引项转换为 label/value 键
MigrateNullFlagFlexFormFractor	eval=null → nullable=true
MigratePasswordAndSaltedPasswordToPasswordTypeFlexFormFractor	将密码 eval 转换为 type=password
MigrateRenderTypeColorpickerToTypeColorFlexFormFractor	renderType=colorPicker → type=color
MigrateRequiredFlagFlexFormFractor	eval=required → required=1
MigrateTypeNoneColsToSizeFlexFormFractor	当 type=none 时，将 cols 转换为 size
RemoveTceFormsDomElementFlexFormFractor	移除 <TCEforms> 包装器

TypoScript 规则（v12）

规则	迁移
MigrateTypoScriptLoginUserAndUsergroupConditionsFractor	将旧式条件转换为 Symfony 表达式
MigrateDeprecatedTypoScriptConditionsFractor	将已弃用的 TypoScript [compatVersion]／旧式条件语法转换为受支持的形式
RemoveConfigDisablePageExternalUrlFractor	移除 config.disablePageExternalUrl
RemoveConfigDoctypeSwitchFractor	移除 config.doctypeSwitch
RemoveConfigMetaCharsetFractor	移除 config.metaCharset
RemoveConfigSendCacheHeadersOnlyWhenLoginDeniedInBranchFractor	移除已弃用的缓存标头配置
RemoveConfigSpamProtectEmailAddressesAsciiOptionFractor	移除 ascii 选项
RemoveNewContentElementWizardOptionsFractor	移除旧式 CE 向导 TSconfig
RemoveWorkspaceModeOptionsFractor	移除工作区模式选项
RenameConfigXhtmlDoctypeToDoctypeFractor	xhtmlDoctype → doctype
RenameTcemainLinkHandlerMailKeyFractor	重命名邮件链接处理程序键
UseConfigArrayForTSFEPropertiesFractor	将 TSFE 属性转换为配置数组

Fluid 规则（套件 ID TYPO3_8）

规则	迁移
ReplaceCaseDefaultWithDefaultCaseFluidFractor	<f:case default="true"> → <f:defaultCase>（v1.0 新增；通过累积级别集合应用）

Fluid 规则（v12）

规则	迁移
AbstractMessageGetSeverityFluidFractor	迁移 Fluid 中的严重性常量

TypoScript 规则（套件 ID TYPO3_13）

这些规则以历史集合名称 Typo3SetList::TYPO3_13 发布（面向 v13 的规则）。在 v14 代码库上应用累积的 Typo3LevelSetList::UP_TO_TYPO3_14 级别集合时，这些规则仍会运行。

规则	迁移
MigrateIncludeTypoScriptSyntaxFractor	<INCLUDE_TYPOSCRIPT: → @import
RemovePageDoktypeRecyclerFromUserTsConfigFractor	从 TSconfig 中移除 recycler doktype

TypoScript 规则（v14）

规则	迁移
MigrateTypoScriptConditionGetTSFEFractor	将 getTSFE() 条件迁移到新 API
MigrateTypoScriptGetDataPathFractor	getData 路径变更
RemoveDuplicateDoktypeRestrictionConfigurationFractor	移除重复的 doktype 限制
RemoveExposeNonexistentUserInForgotPasswordDialogSettingInFeLoginFractor	移除已弃用的 fe_login 设置
RemoveExternalOptionFromTypoScriptFractor	移除 external 选项
RemoveFrontendAssetConcatenationAndCompressionFractor	移除资源串联/压缩设置
RemoveModWebLayoutDefLangBindingFractor	移除 mod.web_layout.defLangBinding
RemoveUserTSConfigAuthBeRedirectToURLFractor	移除 auth.BE.redirectToURL

Fluid 规则（v14）

规则	迁移
ChangeLogoutHandlingInFeLoginFractor	迁移 fe_login 登出处理方式

YAML 规则（v14）

规则	迁移
MigrateLegacyFormTemplatesFractor	迁移旧版 EXT:form 模板

Htaccess 规则（v14）

规则	迁移
RemoveUploadsFromDefaultHtaccessFractor	从 .htaccess 中移除 /uploads/

详细参考

如果任务需要详细示例、较长的模板、故障排查矩阵、附录或上文未包含的部分，请阅读完整指南。对于范围较窄的任务，请勿加载此文件，以便该技能遵循渐进式披露。