Fractor Fluid Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require a9f/fractor-fluid --dev
   

   Ensure it’s added to your devDependencies (as it’s a tooling package).

2. Register the Processor In your Fractor configuration (typically config/fractor.php), add the FluidFileProcessor to the $processors array:

   'processors' => [
       \A9F\FractorFluid\Processor\FluidFileProcessor::class,
   ],
   

3. First Use Case: Basic Fluid Template Analysis Run Fractor with the --analyze flag to scan .html or .fluid files (common Fluid extensions):

   php artisan fractor:analyze app/Resources/Views/
   

   The processor will parse Fluid syntax (e.g., {namespace}, {layout}, {section}) and flag issues like:

   • Missing namespace directives.
   • Unclosed {section} blocks.
   • Invalid variable syntax ({foo} vs. {bar.baz}).

Implementation Patterns

Workflow: Integrating Fluid Rules

1. Define Custom Rules Create a rule class implementing FluidFractorRule:

   use A9F\FractorFluid\Contract\FluidFractorRule;
   
   class CustomFluidRule implements FluidFractorRule {
       public function check(string $content): array {
           $errors = [];
           if (strpos($content, '{invalid_syntax}') !== false) {
               $errors[] = 'Invalid Fluid syntax detected.';
           }
           return $errors;
       }
   }
   

2. Tag and Register the Rule Bind the rule in a service provider (e.g., AppServiceProvider):

   public function register() {
       $this->app->tag([CustomFluidRule::class], 'fractor.fluid_rule');
   }
   

3. Trigger Analysis in CI/CD Add a script to your composer.json:

   "scripts": {
       "test:fluid": "php artisan fractor:analyze resources/views --format=json > fluid-report.json"
   }
   

   Use the output to gate deployments (e.g., fail if errors exist).

Integration Tips

• Laravel Blade Compatibility: If using Blade + Fluid hybrid templates, exclude Blade files from analysis by filtering file extensions in FluidFileProcessor.

  protected function shouldProcess(string $path): bool {
      return str_ends_with($path, ['.fluid', '.html']);
  }
  

• Dynamic Rule Loading: Load rules from a config file (e.g., config/fractor/fluid_rules.php) for maintainability:

  'rules' => [
      \App\Rules\DeprecatedFluidTagRule::class,
      \App\Rules\SectionNamingConventionRule::class,
  ],
  

• Pre-commit Hooks: Use husky or pre-commit to run Fractor on Fluid files before commits:

  # .husky/pre-commit
  php artisan fractor:analyze resources/views --format=compact
  

Gotchas and Tips

Pitfalls

1. False Positives in Complex Templates

   • Fluid comments (<!--{...}-->) or escaped braces (\{...}) may trigger false errors.
   • Fix: Extend FluidFileProcessor to skip commented/escaped blocks:

     protected function extractFluidBlocks(string $content): array {
         // Add logic to ignore comments/escaped braces
         return preg_match_all('/\{\{.*?\}\}/s', $content, $matches);
     }
     

2. Performance with Large Projects

   • Parsing thousands of Fluid files can be slow.
   • Fix: Cache analysis results or limit scans to changed files:

     // In FluidFileProcessor
     protected function getFilesToProcess(): array {
         return array_diff(scandir($this->path), ['.git', 'node_modules']);
     }
     

3. Rule Conflicts

   • Multiple rules may flag the same issue (e.g., missing namespace and "invalid root block").
   • Fix: Use rule priority in FluidFractorRule:

     public function getPriority(): int {
         return 10; // Lower = higher priority
     }
     

Debugging

• Enable Verbose Output: Run with --verbose to see raw Fluid parsing:

  php artisan fractor:analyze --verbose
  

• Inspect Processor Logic: Override FluidFileProcessor methods like process() to log intermediate steps:

  public function process(string $content): string {
      \Log::debug('Processing: ', ['content' => $content]);
      return parent::process($content);
  }
  

Extension Points

1. Custom Fluid Dialects Extend FluidFileProcessor to support non-standard Fluid syntax (e.g., TYPO3-specific tags):

   protected function getFluidPattern(): string {
       return '/\{\{.*?\}\}/s'; // Override regex for custom syntax
   }
   

2. Post-Processing Hooks Add callbacks after rule checks via the afterCheck event:

   // In a service provider
   \Event::listen('fractor.fluid.after_check', function ($content, $errors) {
       if (count($errors)) {
           \Log::warning('Fluid errors found:', $errors);
       }
   });
   

3. Visual Studio Code Integration Use the fractor-report.json output to create a VSCode problem matcher for inline errors:

   // .vscode/settings.json
   "problemMatcher": [
       {
           "pattern": {
               "regexp": "^(.+?):(\\d+):\\d+:\\s+(warning|error)\\s+(.*)$",
               "file": 1,
               "line": 2,
               "severity": 3,
               "message": 4
           }
       }
   ]