typo3-fractor

TYPO3 Fractor スキル

ソース：https://github.com/dirnbauer/webconsulting-skills

Fractor は、TYPO3 のアップグレードに伴う PHP 以外のマイグレーションを自動化する、汎用ファイルリファクタリングツールです。FlexForms、TypoScript、Fluid テンプレート、YAML、XLIFF 翻訳ファイル、Htaccess ファイル、composer.json を移行することで、Rector（PHP を処理）を補完します。Fractor は v1.0（2026 年 7 月）以降安定しており、Simon Schaufelberger と Andreas Wolf がメンテナンスし、TYPO3 コミュニティの予算から一部資金提供を受けています。

対象： このスキルコレクションは TYPO3 v14.x が対象です。アップストリームの Fractor セットは、引き続き TYPO3_12、TYPO3_13 などの名前が付いている場合があります。これらは、コードを v14 のコードベースへ移行する際に適用するルールの、過去のバンドル識別子です。

TYPO3 API を優先： カスタム実装を作成する前に、必ず TYPO3 の組み込み API、コア機能、確立された規約を使用してください。使用する API とメソッドが TYPO3 v14 に存在し、非推奨ではないことを、公式 TYPO3 ドキュメントで必ず確認してください。

安全性： 本番環境で 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 はプロジェクトのオートローダーを読み込み、インストール済みの TYPO3 パッケージを解析できる PHP バージョンを必要とします。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	Password の 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 プロパティ → config 配列

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/ を削除

詳細リファレンス

詳細な例、長いテンプレート、トラブルシューティング用マトリックス、付録、または上記に含まれていないセクションが必要な場合は、完全ガイドをお読みください。タスクの範囲が限定されている場合は、このファイルを読み込まないようにして、スキルが段階的に情報を開示できるようにしてください。