Getting Started

Minimal Steps

Installation Add the package to your project via Composer:
```
composer require --dev ssch/typo3-rector
```
Initialize the Rector config:
```
vendor/bin/typo3-init
```
This generates a rector.php file in your project root.
First Run (Dry Run) Preview changes before applying them:
```
vendor/bin/rector process --dry-run
```
Review the output to ensure the transformations align with your migration goals.
Apply Changes Once satisfied with the preview, run:
```
vendor/bin/rector process
```
Commit the changes to version control.

Where to Look First

Documentation: Official Docs Focus on:
- Installation Guide
- Rule Reference (lists all available TYPO3-specific rules)
- Version Matrix to confirm compatibility with your TYPO3 version.

Config File: rector.php Key sections:

return static::configure()
    ->withPaths([__DIR__.'/Classes', __DIR__.'/Tests'])
    ->withRules([...]) // Add TYPO3-specific rules here
    ->withPreparedSets(); // Use predefined sets (e.g., `typo3:code-quality`)

First Use Case

Migrate from TYPO3 v10 to v14:

Configure the rector.php to target v14:

->withPreparedSets()
    ->withSet(Typo3SetList::TYPO3_10_14),

Run Rector with a dry run to validate changes:

vendor/bin/rector process --dry-run --level=max

Address any edge cases manually, then commit and test thoroughly.

Implementation Patterns

Core Workflows

1. Version-Specific Migrations

Pattern: Use PreparedSets to apply all rules for a TYPO3 version upgrade.
```
->withPreparedSets()
    ->withSet(Typo3SetList::TYPO3_11_12),
```

Customization: Override specific rules in withRules():

->withRules([
    MigrateTypoScriptFrontendControllerConfigRector::class,
    RemoveTypo3VersionChecksRector::class => [
        RemoveTypo3VersionChecksRector::TARGET_VERSION => 14,
    ],
]),

2. Incremental Refactoring

Pattern: Run Rector on a subset of files (e.g., a single extension):
```
vendor/bin/rector process --paths=Extensions/MyExtension/Classes
```
Combine with ECS: Use Easy Coding Standard to auto-format output:
```
vendor/bin/ecs check src --fix
```

3. Testing Migrations

Pattern: Test migrations in a CI pipeline:

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

Tip: Use --level=max to enforce strict checks in CI.

4. Custom Rules

Pattern: Extend Rector with custom rules:

vendor/bin/rector create-rule MyCustomRule

Then register it in rector.php:

->withRules([
    \Vendor\MyCustomRule::class,
]),

Integration Tips

TYPO3 Extensions: Target Classes/ and Tests/ directories:

->withPaths([
    __DIR__.'/Classes',
    __DIR__.'/Tests/Unit',
]),

Fluid Templates: Use typo3-rector for PHP migrations; pair with fractor for Fluid/TypoScript:
```
composer require --dev andreaswolf/fractor
vendor/bin/fractor process
```
Database Updates: Run Rector before database migrations to avoid conflicts with deprecated code.

Gotchas and Tips

Pitfalls

Global State Changes:
- Issue: Rules like MigrateGLOBALS['TSFE']->fe_user may break if your code relies on global state.
- Fix: Test thoroughly in a staging environment. Use @ignore annotations for problematic cases:
```
/** @ignore Rector\Typo3\Rector\ClassMethod\MigrateFeUserRector */
public function oldMethod() { ... }
```
False Positives:
- Issue: Rector may flag legacy code as deprecated even if it’s safe (e.g., GeneralUtility::makeInstance()).
- Fix: Exclude specific files/directories:
```
->withExcludedPaths([
    __DIR__.'/Vendor/LegacyCode',
]),
```
Coding Standards:
- Issue: Rector’s output may violate PSR-12 or your team’s standards.
- Fix: Configure ECS to run after Rector:
```
vendor/bin/ecs check src --fix
```
  Use the provided ECS config as a baseline.
Performance:
- Issue: Large codebases may slow down Rector.
- Fix: Process files incrementally or parallelize:
```
vendor/bin/rector process --parallel
```

Debugging

Dry Run with Verbosity:
```
vendor/bin/rector process --dry-run -vv
```
This shows why each change is applied.

Rule-Specific Debugging: Disable a rule temporarily:

->withRules([
    MigrateTypoScriptFrontendControllerConfigRector::class => false,
]),

Git Integration: Use git diff to review changes:

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

Extension Points

Custom Rule Conditions: Use ShouldRunCondition to control rule execution:

class MyCustomCondition implements ShouldRunCondition
{
    public function shouldRun(): bool
    {
        return !app()->environment('production');
    }
}

->withRuleWithCondition(MyCustomRule::class, new MyCustomCondition()),

Post-Rector Hooks: Chain Rector with other tools (e.g., PHPStan) via a custom script:

# post-rector.sh
vendor/bin/rector process && vendor/bin/phpstan analyse --level=max

TYPO3-Specific Annotations: Use @var or @method annotations to guide Rector:

/**
 * @var \TYPO3\CMS\Core\Utility\GeneralUtility
 */
private $generalUtility;

Configuration Quirks

typo3-init Overrides: Running vendor/bin/typo3-init again may reset your rector.php. Backup or merge changes manually.
Rector Version Pinning: Pin ssch/typo3-rector to a specific version in composer.json to avoid unexpected rule changes:
```
"require-dev": {
    "ssch/typo3-rector": "^3.14.0"
}
```
PHP Version Mismatches: Ensure your php-parser version matches Rector’s requirements (e.g., PHP 8.1+ for Rector v2.4+).

Pro Tips

Atomic Commits: Run Rector on one rule at a time for safer merges:

vendor/bin/rector process --rules=MigrateTypoScriptFrontendControllerConfigRector

Backup Strategy: Use git stash before running Rector on large codebases:
```
git stash && vendor/bin/rector process && git stash pop
```

TYPO3 Compatibility: For TYPO3 v12+, enable the typo3:code-quality set:

->withPreparedSets()
    ->withSet(Typo3SetList::TYPO3_CODE_QUALITY),

Typo3 Rector Laravel Package