Getting Started

Minimal Steps to Begin

Installation:
```
composer require --dev ssch/typo3-rector
vendor/bin/typo3-init
```
This generates a basic rector.php config file in your project root.
First Dry Run:
```
vendor/bin/rector process --dry-run
```
Review the output to understand what changes will be applied without modifying your code.
Apply Changes:
```
vendor/bin/rector process
```
Run this only after verifying the dry run output.

Where to Look First

Documentation: Start with the Best Practice Guide and All Rectors Overview.

Configuration: Edit rector.php to customize rulesets and paths. Example:

return RectorConfig::configure()
    ->withSets([
        Typo3SetList::TYPO3_120,
        Typo3SetList::TCA_120,
    ])
    ->withPaths([__DIR__ . '/Classes']);

ClassAliasMap: If upgrading across versions (e.g., TYPO3 v8 → v10), add ClassAliasMap entries to composer.json under extra:

"extra": {
    "typo3/class-alias-loader": {
        "class-alias-maps": [
            "vendor/ssch/typo3-rector/Migrations/TYPO3/10.4/typo3/sysext/core/Migrations/Code/ClassAliasMap.php"
        ]
    }
}

First Use Case: Upgrading TYPO3 v10 to v12

Install and Configure:

composer require --dev ssch/typo3-rector
vendor/bin/typo3-init

Apply Rulesets Sequentially:

return RectorConfig::configure()
    ->withSets([
        Typo3SetList::TYPO3_104,  // Start with current version
        Typo3SetList::TYPO3_115,  // Then intermediate versions
        Typo3SetList::TYPO3_120,  // Finally target version
    ])
    ->withPaths([__DIR__ . '/Classes']);

Dry Run and Test:
```
vendor/bin/rector process --dry-run
```
Test thoroughly before committing changes.

Implementation Patterns

Workflows

Version-Specific Upgrades:
- Use Typo3SetList::TYPO3_XY for core changes (e.g., TYPO3_120 for TYPO3 v12).
- Use Typo3SetList::TCA_XY for TCA-specific changes (e.g., TCA_120 for TCA in v12).
- Example for incremental upgrades:
```
->withSets([
    Typo3SetList::TYPO3_104,
    Typo3SetList::TYPO3_115,
    Typo3SetList::TYPO3_120,
])
```

Targeted Path Processing:

Process specific directories or files:

->withPaths([
    __DIR__ . '/Classes/Controller',
    __DIR__ . '/Configuration/TCA/Overrides',
])

Combining Rulesets:

Mix TCA and core rulesets for comprehensive upgrades:

->withSets([
    Typo3SetList::TCA_120,    // TCA-specific rules
    Typo3SetList::TYPO3_120,  // Core rules
])

ClassAliasMap for Multi-Version Jumps:
- If skipping versions (e.g., v8 → v10), include ClassAliasMap for all intermediate versions in composer.json.

Integration Tips

Pre-Commit Hooks: Add a Git hook to run Rector in dry mode before commits:

# .git/hooks/pre-commit
#!/bin/bash
vendor/bin/rector process --dry-run || exit 1

CI/CD Pipeline: Use Rector in CI to enforce upgrades:

# .github/workflows/rector.yml
jobs:
  rector:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: composer require --dev ssch/typo3-rector
      - run: vendor/bin/rector process --dry-run

Symfony Container Integration: For rules like AddAutoconfigureAttributeToClassRector, ensure the Symfony container XML is generated:
```
->withSymfonyContainerXml(__DIR__ . '/var/cache/dev/App_KernelDevDebugContainer.xml')
```
Clear TYPO3 cache first:
```
vendor/bin/typo3 cache:flush
```
Parallel Processing: Use --parallel for large codebases:
```
vendor/bin/rector process --parallel
```

Gotchas and Tips

Pitfalls

Production Safety:
- Never run Rector in production. Always test in a development/staging environment with version control.
- Use --dry-run to preview changes:
```
vendor/bin/rector process --dry-run
```
Invalid TCA Structures:
- Rector requires valid TCA structures (e.g., ctrl and columns keys). Example:
```
return [
    'ctrl' => [],    // Required
    'columns' => [], // Required
];
```
- For overrides, explicitly define types (e.g., 'type' => 'select' for doktype items).

ClassAliasMap Misconfiguration:

Missing or incorrect ClassAliasMap entries will cause Rector to fail silently or apply incorrect migrations.

Example for v8 → v10:

"extra": {
    "typo3/class-alias-loader": {
        "class-alias-maps": [
            "vendor/ssch/typo3-rector/Migrations/TYPO3/8.7/typo3/sysext/core/Migrations/Code/ClassAliasMap.php",
            "vendor/ssch/typo3-rector/Migrations/TYPO3/10.4/typo3/sysext/core/Migrations/Code/ClassAliasMap.php"
        ]
    }
}

Coding Standards:
- Rector outputs unformatted code. Use ECS (Easy Coding Standard) to auto-format:
```
composer require --dev symplify/easy-coding-standard
vendor/bin/ecs check src
```
- Configure ECS with the provided setup.
Symfony Container Dependencies:
- Rules like AddAutoconfigureAttributeToClassRector require:
  - ssch/typo3-debug-dump-pass installed.
  - A valid Symfony container XML file (generated via vendor/bin/typo3 cache:flush).
  - Correct path in rector.php:
```
->withSymfonyContainerXml(__DIR__ . '/var/cache/dev/App_KernelDevDebugContainer.xml')
```
Partial Rule Application:
- Some rules (e.g., ExtEmConfRector) require explicit configuration. Example:
```
->withRule(ExtEmConfRector::class)
```

Debugging Tips

Verbose Output: Use --verbose to debug rule application:
```
vendor/bin/rector process --verbose
```

Rule-Specific Debugging:

Isolate problematic rules by running them individually:

vendor/bin/rector process --rules=Ssch\TYPO3Rector\TYPO312\RenameClassConstantRector

Git Diff Analysis: After a dry run, compare changes with Git:

git diff --name-only | xargs vendor/bin/rector process --dry-run

ClassAliasMap Validation:
- Test ClassAliasMap entries by running Rector on a single file:
```
vendor/bin/rector process Classes/Controller/SomeController.php --dry-run
```

Extension Points

Custom Rules: Extend Rector by creating custom rules. Example:

// CustomRector.php
namespace App\Rector;

use PhpParser\Node;
use Rector\Core\Rector\AbstractRector;

class CustomR

Typo3 Rector Laravel Package