#601

Global Rank · of 601 Skills

typo3-fractor AI Agent Skill

View Source: dirnbauer/webconsulting-skills

Safe

Installation

npx skills add dirnbauer/webconsulting-skills --skill typo3-fractor

Installs

TYPO3 Fractor Skill

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

Tool	Handles	Package
Rector	PHP code (classes, TCA PHP, ext_localconf, etc.)	`ssch/typo3-rector`
Fractor	Non-PHP files (FlexForms, TypoScript, Fluid, YAML, Htaccess, composer.json)	`a9f/typo3-fractor`

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:

Set List	Includes
`Typo3LevelSetList::UP_TO_TYPO3_10`	Imports `UP_TO_TYPO3_9` plus `TYPO3_10` rules only (see package `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

Version-Specific Sets

Apply rules for a single version only:

Set List	Description
`Typo3SetList::TYPO3_12`	v12 rules only
`Typo3SetList::TYPO3_13`	v13 rules only
`Typo3SetList::TYPO3_14`	v14 rules only

5. Rules by File Type and Version

FlexForm Rules (v12)

Rule	Migration
`MigrateEmailFlagToEmailTypeFlexFormFractor`	`eval=email` → `type=email`
`MigrateEvalIntAndDouble2ToTypeNumberFlexFormFractor`	`eval=int/double2` → `type=number`
`MigrateInternalTypeFolderToTypeFolderFlexFormFractor`	`internalType=folder` → `type=folder`
`MigrateItemsIndexedKeysToAssociativeFractor`	Indexed items → `label`/`value` keys
`MigrateNullFlagFlexFormFractor`	`eval=null` → `nullable=true`
`MigratePasswordAndSaltedPasswordToPasswordTypeFlexFormFractor`	Password eval → `type=password`
`MigrateRenderTypeColorpickerToTypeColorFlexFormFractor`	`renderType=colorPicker` → `type=color`
`MigrateRequiredFlagFlexFormFractor`	`eval=required` → `required=1`
`MigrateTypeNoneColsToSizeFlexFormFractor`	`cols` → `size` for type=none
`RemoveTceFormsDomElementFlexFormFractor`	Remove `<TCEforms>` wrapper

TypoScript Rules (v12)

Rule	Migration
`MigrateTypoScriptLoginUserAndUsergroupConditionsFractor`	Legacy conditions → Symfony expressions
`MigrateDeprecatedTypoScriptConditionsFractor`	Deprecated TypoScript `[compatVersion]` / old condition syntax → supported forms
`RemoveConfigDisablePageExternalUrlFractor`	Remove `config.disablePageExternalUrl`
`RemoveConfigDoctypeSwitchFractor`	Remove `config.doctypeSwitch`
`RemoveConfigMetaCharsetFractor`	Remove `config.metaCharset`
`RemoveConfigSendCacheHeadersOnlyWhenLoginDeniedInBranchFractor`	Remove deprecated cache header config
`RemoveConfigSpamProtectEmailAddressesAsciiOptionFractor`	Remove `ascii` option
`RemoveNewContentElementWizardOptionsFractor`	Remove legacy CE wizard TSconfig
`RemoveWorkspaceModeOptionsFractor`	Remove workspace mode options
`RenameConfigXhtmlDoctypeToDoctypeFractor`	`xhtmlDoctype` → `doctype`
`RenameTcemainLinkHandlerMailKeyFractor`	Rename mail link handler key
`UseConfigArrayForTSFEPropertiesFractor`	TSFE properties → config array

Fluid Rules (v12)

Rule	Migration
`AbstractMessageGetSeverityFluidFractor`	Migrate severity constants in Fluid

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.

Rule	Migration
`MigrateIncludeTypoScriptSyntaxFractor`	`<INCLUDE_TYPOSCRIPT:` → `@import`
`RemovePageDoktypeRecyclerFromUserTsConfigFractor`	Remove recycler doktype from TSconfig

TypoScript Rules (v14)

Rule	Migration
`MigrateTypoScriptConditionGetTSFEFractor`	`getTSFE()` conditions → new API
`MigrateTypoScriptGetDataPathFractor`	getData path changes
`RemoveDuplicateDoktypeRestrictionConfigurationFractor`	Remove duplicate doktype restrictions
`RemoveExposeNonexistentUserInForgotPasswordDialogSettingInFeLoginFractor`	Remove deprecated fe_login setting
`RemoveExternalOptionFromTypoScriptFractor`	Remove `external` option
`RemoveFrontendAssetConcatenationAndCompressionFractor`	Remove asset concatenation/compression settings
`RemoveModWebLayoutDefLangBindingFractor`	Remove `mod.web_layout.defLangBinding`
`RemoveUserTSConfigAuthBeRedirectToURLFractor`	Remove `auth.BE.redirectToURL`

Fluid Rules (v14)

Rule	Migration
`ChangeLogoutHandlingInFeLoginFractor`	Migrate fe_login logout handling

YAML Rules (v14)

Rule	Migration
`MigrateLegacyFormTemplatesFractor`	Migrate legacy EXT:form templates

Htaccess Rules (v14)

Rule	Migration
`RemoveUploadsFromDefaultHtaccessFractor`	Remove `/uploads/` from .htaccess

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

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

Recommended Order

git checkout -b feature/typo3-upgrade
Run Rector (PHP migrations)        → vendor/bin/rector process
Run Fractor (non-PHP migrations)   → vendor/bin/fractor process
Run PHP-CS-Fixer (code style)      → vendor/bin/php-cs-fixer fix
Run PHPStan (static analysis)      → vendor/bin/phpstan analyse
Run Tests                          → vendor/bin/phpunit
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

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

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

Credits & Attribution

Thanks to Andreas Wolf for creating and maintaining Fractor.
Thanks to Netresearch DTT GmbH for their contributions to the TYPO3 community.

Installs

Installs 16

Global Rank #601 of 601

Security Audit

ath Safe

socket Safe

Alerts: 0 Score: 90

snyk Low

View Source

dirnbauer/webconsulting-skills

Power your AI Agents with
the best open-source models.

Drop-in OpenAI-compatible API. No data leaves Europe.

Explore Inference API

GLM

GLM 5

$1.00 / $3.20

per M tokens

Kimi

Kimi K2.5

$0.60 / $2.80

per M tokens

MiniMax

MiniMax M2.5

$0.30 / $1.20

per M tokens

Qwen

Qwen3.5 122B

$0.40 / $3.00

per M tokens

How to use this skill

Install typo3-fractor by running npx skills add dirnbauer/webconsulting-skills --skill typo3-fractor in your project directory. Run the install command above in your project directory. The skill file will be downloaded from GitHub and placed in your project.

No configuration needed. Your AI agent (Claude Code, Cursor, Windsurf, etc.) automatically detects installed skills and uses them as context when generating code.

The skill enhances your agent's understanding of typo3-fractor, helping it follow established patterns, avoid common mistakes, and produce production-ready output.

What you get

Skills are plain-text instruction files — not executable code. They encode expert knowledge about frameworks, languages, or tools that your AI agent reads to improve its output. This means zero runtime overhead, no dependency conflicts, and full transparency: you can read and review every instruction before installing.

Compatibility

This skill works with any AI coding agent that supports the skills.sh format, including Claude Code (Anthropic), Cursor, Windsurf, Cline, Aider, and other tools that read project-level context files. Skills are framework-agnostic at the transport level — the content inside determines which language or framework it applies to.

Data sourced from the skills.sh registry and GitHub. Install counts and security audits are updated regularly.

Made in Europe

Chat with 100+ AI Models in one App.

Use Claude, ChatGPT, Gemini alongside with EU-Hosted Models like Deepseek, GLM-5, Kimi K2.5 and many more.

Start for free View pricing

typo3-fractor AI Agent Skill

TYPO3 Fractor Skill

Fractor vs Rector

1. Installation

2. Configuration

Quick Start

Manual Configuration

Configuration for v14

Skip Rules or Files

Apply Single Rules

3. Running Fractor

Dry Run (Preview)

Apply Changes

Run Single Rule from Set

With DDEV

4. Available Set Lists

Level Sets (Cumulative)

Version-Specific Sets

5. Rules by File Type and Version

FlexForm Rules (v12)

TypoScript Rules (v12)

Fluid Rules (v12)

TypoScript rules (bundle id TYPO3_13)

TypoScript Rules (v14)

Fluid Rules (v14)

YAML Rules (v14)

Htaccess Rules (v14)

6. Code Style Configuration

TypoScript Formatting

XML/FlexForm Formatting

File Extension Filtering

7. Writing Custom Rules

Custom XML/FlexForm Rule

Register Custom Rule

8. Upgrade Workflow Integration

Recommended Order

Combined fractor.php for Extension Development

9. Troubleshooting

Fractor Fails to Parse TypoScript

FlexForm Changes Not Applied

Formatting Changes Unexpected

Running Fractor in CI

Appendix

Credits & Attribution

Installs

Security Audit

View Source

Power your AI Agents with the best open-source models.

How to use this skill

What you get

Compatibility

Chat with 100+ AI Models in one App.

TypoScript rules (bundle id `TYPO3_13`)

Power your AI Agents with
the best open-source models.