Fractor Typoscript Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require a9f/fractor-typoscript --dev
   

   Add to your fractor.json (or fractor.php):

   {
     "extensions": [
       "a9f/fractor-typoscript"
     ]
   }
   

2. First Use Case Process a TypoScript file (ext_typoscript/setup.typoscript or Configuration/TypoScript/setup.typoscript):

   fractor process path/to/file.typoscript
   

3. Key Files to Review

   • src/Processor/TypoScriptProcessor.php (core logic)
   • src/Rule/ (default rules, if any exist)
   • tests/ (for edge cases and examples)

Implementation Patterns

Common Workflows

1. Basic File Processing

   use A9F\FractorTypoScript\Processor\TypoScriptProcessor;
   
   $processor = new TypoScriptProcessor();
   $result = $processor->process(file_get_contents('setup.typoscript'));
   file_put_contents('setup.typoscript', $result);
   

2. Custom Rule Integration Extend A9F\FractorTypoScript\Rule\AbstractRule to create domain-specific rules:

   namespace App\Fractor\Rules;
   
   use A9F\FractorTypoScript\Rule\AbstractRule;
   
   class NoHardcodedPageIds extends AbstractRule {
       protected function getPattern(): string {
           return '/page = \d+/';
       }
   }
   

   Register in fractor.php:

   'rules' => [
       \App\Fractor\Rules\NoHardcodedPageIds::class,
   ],
   

3. Integration with Laravel Use Laravel’s service container to bind the processor:

   $this->app->bind(TypoScriptProcessor::class, function ($app) {
       return new TypoScriptProcessor($app['config']['fractor.typoscript']);
   });
   

   Trigger via Artisan command:

   php artisan fractor:process path/to/setup.typoscript
   

4. CI/CD Pipeline Add to composer.json scripts:

   "scripts": {
       "post-update-cmd": [
           "@fractor process typo3conf/ext/*/Configuration/TypoScript/setup.typoscript"
       ]
   }
   

Gotchas and Tips

Pitfalls

1. Parser Limitations

   • The underlying helmich/typo3-typoscript-parser may struggle with:
     • Malformed TypoScript (e.g., unclosed brackets, missing semicolons).
     • Workaround: Validate files with typo3/sysext/core/Classes/Utility/TypoScriptUtility.php before processing.
   • Complex TypoScript constructs (e.g., stdWrap with nested conditions) might not parse correctly. Tip: Test with real-world files early.

2. Rule Conflicts

   • Overlapping regex patterns in custom rules can cause unintended replacements. Tip: Use getPriority() in AbstractRule to control execution order.

3. File Caching

   • Fractor caches processed files by default. Disable with:

     $processor->setCacheEnabled(false);
     

4. TYPO3 Version Compatibility

   • The package assumes TypoScript v7+ syntax. Older syntax (e.g., lib.) may break. Tip: Use TYPO3\CMS\Core\Utility\VersionNumberUtility to check compatibility.

Debugging Tips

• Enable Verbose Output

  fractor process --verbose path/to/file.typoscript
  

• Inspect AST Use the parser’s debug mode:

  $parser = new \Helmich\Typo3TypoScriptParser\Parser();
  $ast = $parser->parse(file_get_contents('setup.typoscript'), true); // Enable debug
  

Extension Points

1. Custom Processors Implement A9F\FractorTypoScript\Processor\ProcessorInterface for non-TypoScript file types (e.g., YAML configs).

2. Pre/Post-Processing Hooks Override TypoScriptProcessor::preProcess() or postProcess() for file-level transformations.

3. Rule Validation Add isApplicable() to rules to skip irrelevant files (e.g., only process setup.typoscript).