Typo3 Fractor

TYPO3 Fractor Skill

Source: https://github.com/dirnbauer/webconsulting-skills

Fractor is a generic file refactoring tool that automates non-PHP migrations for TYPO3 upgrades. It complements Rector (which handles PHP) by migrating FlexForms, TypoScript, Fluid templates, YAML, Htaccess files, and composer.json.

Target: TYPO3 v14.x for this skill collection. Upstream Fractor sets may still be named TYPO3_12, TYPO3_13, etc. — those are historical bundle identifiers for rules you apply while moving code toward a v14 codebase.

TYPO3 API First: Always use TYPO3's built-in APIs, core features, and established conventions before creating custom implementations. Always verify that the APIs and methods you use exist and are not deprecated in TYPO3 v14 by checking the official TYPO3 documentation.

Safety: Never run Fractor on production. Always run on a development environment with version control. Review and test changes before releasing.

Fractor vs Rector

Use both together for complete TYPO3 upgrades. See the typo3-extension-upgrade skill for the full workflow.

1. Installation

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

Important: Like Rector, Fractor loads the project autoloader and requires a PHP version

that can parse the installed TYPO3 packages. For TYPO3 v14 targets, run Fractor with

PHP 8.2+. Use DDEV or a container if your local PHP is older.

Always run Fractor, never skip it. Non-PHP files (FlexForms, TypoScript, Fluid) contain

version-specific patterns that are easy to miss in manual review. Fractor rules are

maintained by the TYPO3 community and cover edge cases.

This meta-package installs all TYPO3-specific file processors:

• a9f/fractor (core engine)
• a9f/fractor-xml (FlexForm/XML processing)
• a9f/fractor-fluid (Fluid template processing)
• a9f/fractor-typoscript (TypoScript/TSconfig processing)
• a9f/fractor-yaml (YAML processing)
• a9f/fractor-htaccess (Htaccess processing)
• a9f/fractor-composer-json (composer.json processing — not installed as a dependency of a9f/typo3-fractor; add composer require --dev a9f/fractor-composer-json if you need it)

2. Configuration

Quick Start

Generate a default config:

vendor/bin/typo3-fractor-init

Manual Configuration

Create fractor.php in your project root:

<?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,
    ]);

Configuration for 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,
    ]);

Skip Rules or Files

<?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,
    ]);

Apply Single Rules

<?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. Running Fractor

Dry Run (Preview)

vendor/bin/fractor process --dry-run

Apply Changes

vendor/bin/fractor process

Run Single Rule from Set

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

With DDEV

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

4. Available Set Lists

Level Sets (Cumulative)

Apply all rules up to a target version:

Version-Specific Sets

Apply rules for a single version only:

5. Rules by File Type and Version

FlexForm Rules (v12)

TypoScript Rules (v12)

Fluid Rules (v12)

TypoScript rules (bundle id TYPO3_13)

These rules are published under the historical set name `Typo3SetList::TYPO3_13` (v13-targeted rules). They still run when you apply the cumulative `Typo3LevelSetList::UP_TO_TYPO3_14` level set on a v14 codebase.

TypoScript Rules (v14)

Fluid Rules (v14)

YAML Rules (v14)

Htaccess Rules (v14)

Detailed Reference

Read the full guide when the task needs detailed examples, long templates, troubleshooting matrices, appendices, or sections not included above. Keep this file unloaded for narrow tasks so the skill follows progressive disclosure.

6. Code Style Configuration

Continues typo3-fractor from full guide.

6. Code Style Configuration

TypoScript Formatting

<?php
use a9f\Fractor\Configuration\FractorConfiguration;
use a9f\FractorTypoScript\Configuration\TypoScriptProcessorOption;
use Helmich\TypoScriptParser\Parser\Printer\PrettyPrinterConfiguration;
use Helmich\TypoScriptParser\Parser\Printer\PrettyPrinterConditionTermination;

return FractorConfiguration::configure()
    ->withPaths([__DIR__ . '/Configuration/'])
    ->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::Keep,
    ]);

Indent character options:

• PrettyPrinterConfiguration::INDENTATION_STYLE_SPACES -- use spaces
• PrettyPrinterConfiguration::INDENTATION_STYLE_TABS -- use tabs
• 'auto' -- detect from file and keep existing

Condition termination options:

• PrettyPrinterConditionTermination::Keep -- keep existing
• PrettyPrinterConditionTermination::EnforceGlobal -- always [global]
• PrettyPrinterConditionTermination::EnforceEnd -- always [end]

XML/FlexForm Formatting

<?php
use a9f\Fractor\Configuration\FractorConfiguration;
use a9f\FractorXml\Configuration\XmlProcessorOption;
use a9f\Fractor\ValueObject\Indent;

return FractorConfiguration::configure()
    ->withPaths([__DIR__ . '/Configuration/'])
    ->withOptions([
        XmlProcessorOption::INDENT_CHARACTER => Indent::STYLE_TAB,
        XmlProcessorOption::INDENT_SIZE => 1,
    ]);

File Extension Filtering

Control which file extensions each processor handles:

<?php
use a9f\Fractor\Configuration\FractorConfiguration;
use a9f\FractorFluid\Configuration\FluidProcessorOption;
use a9f\FractorTypoScript\Configuration\TypoScriptProcessorOption;
use a9f\FractorXml\Configuration\XmlProcessorOption;
use a9f\FractorYaml\Configuration\YamlProcessorOption;

return FractorConfiguration::configure()
    ->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'],
    ]);

Default extensions:

• Fluid: html, xml, txt
• TypoScript: typoscript, tsconfig, ts
• XML: xml
• YAML: yaml, yml

7. Writing Custom Rules

Continues typo3-fractor from full guide.

7. Writing Custom Rules

Custom XML/FlexForm Rule

Extend AbstractXmlFractor (in package a9f/fractor-xml). XmlFractor in a9f\FractorXml\Contract is the interface; the abstract base provides the DOM visitor wiring.

<?php
declare(strict_types=1);

namespace Vendor\MyExtension\Fractor;

use a9f\FractorXml\AbstractXmlFractor;
use DOMNode;
use Symplify\RuleDocGenerator\ValueObject\RuleDefinition;

final class MyCustomFlexFormFractor extends AbstractXmlFractor
{
    public function canHandle(\DOMNode $node): bool
    {
        return $node->nodeName === 'config'
            && $node->parentNode instanceof \DOMElement;
    }

    public function refactor(DOMNode $node): DOMNode|int|null
    {
        // Modify the DOM node
        return $node;
    }

    public function getRuleDefinition(): RuleDefinition
    {
        return new RuleDefinition('Migrate custom FlexForm configuration', []);
    }
}

Register Custom Rule

<?php
// fractor.php
use a9f\Fractor\Configuration\FractorConfiguration;
use Vendor\MyExtension\Fractor\MyCustomFlexFormFractor;

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

8. Upgrade Workflow Integration

Continues typo3-fractor from full guide.

8. Upgrade Workflow Integration

Recommended Order

1. git checkout -b feature/typo3-upgrade
2. Run Rector (PHP migrations)        → vendor/bin/rector process
3. Run Fractor (non-PHP migrations)   → vendor/bin/fractor process
4. Run PHP-CS-Fixer (code style)      → vendor/bin/php-cs-fixer fix
5. Run PHPStan (static analysis)      → vendor/bin/phpstan analyse
6. Run Tests                          → vendor/bin/phpunit
7. Manual testing in target version

Combined fractor.php for Extension Development

<?php
declare(strict_types=1);

use a9f\Fractor\Configuration\FractorConfiguration;
use a9f\Typo3Fractor\Set\Typo3LevelSetList;
use a9f\FractorTypoScript\Configuration\TypoScriptProcessorOption;
use Helmich\TypoScriptParser\Parser\Printer\PrettyPrinterConfiguration;

return FractorConfiguration::configure()
    ->withPaths([
        __DIR__ . '/Configuration/',
        __DIR__ . '/Resources/',
    ])
    ->withSkip([
        __DIR__ . '/Resources/Public/',
    ])
    ->withSets([
        Typo3LevelSetList::UP_TO_TYPO3_14,
    ])
    ->withOptions([
        TypoScriptProcessorOption::INDENT_SIZE => 4,
        TypoScriptProcessorOption::INDENT_CHARACTER => PrettyPrinterConfiguration::INDENTATION_STYLE_SPACES,
    ]);

9. Troubleshooting

Continues typo3-fractor from full guide.

9. Troubleshooting

Fractor Fails to Parse TypoScript

# Check for syntax errors in TypoScript first
# Fractor uses helmich/typo3-typoscript-parser which requires valid TypoScript

# Skip problematic files
vendor/bin/fractor process --dry-run
# Then add them to withSkip() in fractor.php

FlexForm Changes Not Applied

# Ensure XML files are in the configured paths
# Check ALLOWED_FILE_EXTENSIONS includes 'xml'
# Verify the FlexForm has the expected structure (<T3DataStructure>)

Formatting Changes Unexpected

# Configure code style explicitly in fractor.php
# Use 'auto' indent detection to preserve existing formatting
# Review withOptions() settings

Running Fractor in CI

# .github/workflows/fractor.yml
- name: Check Fractor
  run: vendor/bin/fractor process --dry-run
  # Fails if any rules would apply = outdated code

Appendix

Continues typo3-fractor from full guide.

Appendix

For Fractor resource links and TYPO3 v14-specific migration notes, see references/resources-and-v14.md.

---

Credits & Attribution

Continues typo3-fractor from full guide.

Credits & Attribution

Thanks to Andreas Wolf for creating and maintaining Fractor.

Source: https://github.com/dirnbauer/webconsulting-skills

TYPO3 Fractor Skill Full Guide

Read only the section that matches the current task. These files continue the main SKILL.md after its lightweight workflow and examples.

Sections

• 6. Code Style Configuration
• 7. Writing Custom Rules
• 8. Upgrade Workflow Integration
• 9. Troubleshooting
• Appendix
• Credits & Attribution

TYPO3 Fractor Appendix

Resources

• Fractor Repository: https://github.com/andreaswolf/fractor
• TYPO3 Fractor Package: https://github.com/andreaswolf/fractor/tree/main/packages/typo3-fractor
• Packagist: https://packagist.org/packages/a9f/typo3-fractor
• TYPO3 Rector (PHP companion): https://github.com/sabbelasichon/typo3-rector
• Related Skills: typo3-extension-upgrade (full upgrade workflow), typo3-rector (PHP migrations)

v14-Only Fractor Targets

The following non-PHP migration targets are v14-specific and handled by Fractor Typo3SetList::TYPO3_14 rules.

What Fractor does not cover

• TCA migrations in PHP files such as ctrl.searchFields, ctrl.is_static, or interface cleanup belong to Rector / manual PHP edits, not Fractor.
• PHP API migrations such as FlexFormService -> FlexFormTools also belong to Rector / manual PHP refactoring.

TypoScript Migrations [v14 only]

• `config.concatenateCss` / `config.concatenateJs` removed — remove these settings; delegate to web server or build tools.
• `config.compressCss` / `config.compressJs` removed — same as above.
• `external` property removed for asset inclusion — remove external = 1 from TypoScript.
• TypoScript condition `getTSFE()` removed — use request-based conditions.

Htaccess Migrations [v14 only]

• Updated default `.htaccess` template (#105244) — Fractor can apply the updated template.

FlexForm / XML Migrations [v14 only]

• Use Fractor for non-PHP FlexForm XML cleanups that are backed by actual Fractor rules in the installed package.
• If the change is a PHP class rename or a TCA migration, switch to the typo3-rector skill instead.