Typo3 Fractor Laravel Package

Getting Started

Minimal Setup

1. Installation Run in your TYPO3 project root:

   composer require a9f/typo3-fractor --dev
   

   Ensure composer.json marks it as a dev dependency (critical for CI/CD safety).

2. Configuration Create config/fractor.php (or adjust path in CLI):

   return \a9f\Fractor\Configuration\FractorConfiguration::configure()
       ->withPaths([__DIR__ . '/Configuration/TypoScript', __DIR__ . '/Resources/Private'])
       ->withSets([\a9f\Typo3Fractor\Set\Typo3LevelSetList::UP_TO_TYPO3_14]);
   

   Verify paths cover all TYPO3 config files (TypoScript, Fluid, YAML).

3. First Dry Run Test changes without modifying files:

   vendor/bin/fractor process --dry-run
   

   • Review output for expected migrations (e.g., addTypoScriptSetup, renameFluidVariable).
   • Fix false positives manually if needed.

First Use Case: TYPO3 Upgrade

• Scenario: Upgrading from TYPO3 v12 to v14.
• Workflow:
  1. Configure UP_TO_TYPO3_14 set in fractor.php.
  2. Run dry run to preview changes:

     vendor/bin/fractor process --dry-run --format=diff
     

  3. Commit changes after validation:

     vendor/bin/fractor process
     git add .
     git commit -m "Apply TYPO3 14 migrations via Fractor"
     

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline Add a pre-merge check (e.g., GitHub Actions):

   - name: Run Fractor Dry Run
     run: vendor/bin/fractor process --dry-run
   

   Fail builds if dry-run detects breaking changes.

2. Team Collaboration

   • Shared Config: Store fractor.php in the repo (not .gitignore).
   • Rule Customization: Extend default sets by creating custom rule files (see docs).

3. File Targeting

   • Granular Paths: Exclude test files or vendor paths:

     ->withPaths([
         __DIR__ . '/Configuration/TypoScript',
         __DIR__ . '/Resources/Private/Templates',
     ])
     ->withExcludedPaths([__DIR__ . '/Tests'])
     

   • File Extensions: Focus on .typoscript, .yaml, or .html files via rules.

Common Patterns

Integration Tips

• Laravel-TYPO3 Projects:
  • Use artisan typo3:sync (if using a bridge package) after Fractor runs to ensure TypoScript is reloaded.
  • Cache busting: Add ?v=2 to static includes if Fractor modifies Fluid templates.
• Testing:
  • Pair with PHPUnit to assert migrations:

    $this->assertFileEquals(
        __DIR__ . '/expected/Setup.typoscript',
        __DIR__ . '/Configuration/TypoScript/Setup.typoscript'
    );
    

Gotchas and Tips

Pitfalls

1. Production Risk

   • Never run fractor process in production. Always use --dry-run first.
   • Workaround: Use environment checks in fractor.php:

     if (app()->environment('production')) {
         throw new \RuntimeException('Fractor disabled in production!');
     }
     

2. False Positives

   • Issue: Rules may misfire on custom TypoScript (e.g., page.10 = TEXT).
   • Fix: Exclude problematic files or override rules:

     ->withCustomRules([new \a9f\Typo3Fractor\Rule\SkipRule('path/to/file.typoscript')])
     

3. Path Resolution

   • Issue: Relative paths may break in subdirectories.
   • Fix: Use absolute paths or realpath():

     ->withPaths([realpath(__DIR__ . '/../Configuration')])
     

4. Rule Conflicts

   • Issue: Multiple rules targeting the same line (e.g., addTypoScriptSetup + removeDeprecated).
   • Fix: Review rule priorities or split into phases.

Debugging

Extension Points

1. Custom Rules Extend core rules by implementing \a9f\Fractor\Rule\RuleInterface:

   class MyCustomRule implements RuleInterface {
       public function process(File $file): void {
           if (str_contains($file->getContent(), 'old_pattern')) {
               $file->replace('old_pattern', 'new_pattern');
           }
       }
   }
   

   Register in fractor.php:

   ->withCustomRules([new MyCustomRule()])
   

2. Pre/Post Hooks Use Symfony’s EventDispatcher to intercept migrations:

   $dispatcher->addListener('fractor.process.start', function () {
       // Pre-processing logic
   });
   

3. TYPO3-Specific Extensions

   • EXT:fluid_styled_content: Add rules for f:format.raw deprecations.
   • EXT:solr: Handle extbase to extbase.typo3 migrations.

Pro Tips

• Backup First: Always commit or stash changes before running Fractor.
• Rule Documentation: Bookmark typo3-fractor-rules.md for quick reference.
• Version Pinning: Lock Fractor to a specific version in composer.json to avoid unexpected rule changes:

  "a9f/typo3-fractor": "1.2.0"
  

• Atomic Commits: Run Fractor per upgrade level (e.g., UP_TO_TYPO3_13, then UP_TO_TYPO3_14) to isolate changes.