Fractor Fluid Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment: The package extends Fractor, a file analysis/modification tool, specifically for Fluid templates (TYPO3’s templating engine). This aligns well with Laravel-based projects using Blade (if Fluid integration is needed) or TYPO3 CMS (if the project is a hybrid Laravel/TYPO3 system).
• Modularity: Since it implements a rule-based processor, it fits into Laravel’s service container and event-driven architectures (e.g., via Illuminate\Filesystem or custom file watchers).
• Extensibility: The FluidFractorRule contract suggests custom rule development, enabling TPMs to enforce consistent Fluid template standards (e.g., variable naming, section structure).

Integration Feasibility

• Laravel Compatibility:
  • Requires PHP 8.1+ (check Laravel version support).
  • Can be integrated via Composer (--dev suggests it’s a dev tool, not runtime dependency).
  • May need custom Artisan commands or event listeners to trigger Fluid file processing.
• TYPO3 vs. Laravel:
  • If using TYPO3, direct integration is straightforward (Fluid is native).
  • If using Blade, requires pre-processing (e.g., convert Blade to Fluid temporarily) or custom parsers.
• Build Tool Integration:
  • Can be hooked into Laravel Forge/Envoyer for deployment-time template validation.
  • Works with Laravel Mix/Vite if Fluid files are part of the asset pipeline.

Technical Risk

• Low-Medium:
  • Dependency Risk: Ties to Fractor (unmaintained? monorepo structure may complicate updates).
  • Fluid-Specific: Blade templates won’t work without conversion; TYPO3 projects must ensure Fluid files are in scope.
  • Performance: Rule processing adds overhead; test with large template sets.
• Mitigation:
  • Isolate: Run as a CI/CD check (e.g., GitHub Actions) rather than runtime.
  • Mock Testing: Validate rules against a subset of templates before full deployment.

Key Questions

1. Use Case Clarity:
   • Is this for TYPO3 integration (native Fluid) or Blade-to-Fluid conversion?
   • Are we enforcing coding standards or auto-fixing templates?
2. Tooling Stack:
   • How will this integrate with existing build/deploy pipelines (e.g., Forge, Envoyer)?
   • Will it replace or complement PHPStan/Pint for template validation?
3. Maintenance:
   • Who will maintain custom rules long-term?
   • Is the Fractor monorepo actively developed, or is this a fork?
4. Alternatives:
   • Could custom Blade directives or Symfony’s StringNode achieve similar goals?
   • Is TYPO3’s Fluid validator sufficient, or does this add unique value?

Integration Approach

Stack Fit

• Laravel + TYPO3 Hybrid:
  • Use Laravel’s service container to bind FluidFileProcessor and inject custom rules.
  • Leverage TYPO3’s Fluid compiler (if applicable) to pre-process templates before Fractor analysis.
• Standalone Laravel (Blade):
  • Requires pre-processing Blade to Fluid (e.g., via a custom script) or custom Blade parsers extending Fractor’s rules.
  • Integrate with Laravel’s view events to hook into template rendering.
• CI/CD Focus:
  • Best suited as a pre-commit hook or GitHub Actions step (e.g., php artisan fractor:check).

Migration Path

1. Pilot Phase:
   • Start with a subset of Fluid templates (e.g., TYPO3 partials or Laravel’s resources/views if converted).
   • Implement one critical rule (e.g., required section headers) to validate feasibility.
2. Tooling Setup:
   • Add to composer.json (--dev).
   • Publish a config file (if needed) for rule customization.
   • Create an Artisan command to run Fractor:

     // Example: app/Console/Commands/RunFractor.php
     public function handle() {
         $processor = app(FluidFileProcessor::class);
         $processor->process(directory: storage_path('app/fluid-templates'));
     }
     

3. CI Integration:
   • Add to .github/workflows/ci.yml:

     - name: Run Fractor
       run: php artisan fractor:check
     

Compatibility

• Fluid Version: Ensure compatibility with the TYPO3 Fluid version in use (e.g., Fluid 2.x vs. 3.x).
• Laravel Version: Test with PHP 8.1+ and Laravel 10.x+ (check for BC breaks).
• Rule Conflicts: Custom rules may clash with existing Fluid syntax (e.g., {namespace} vs. {section}).

Sequencing

1. Pre-Development:
   • Define template standards (e.g., "All sections must have a header variable").
   • Develop custom rules extending FluidFractorRule.
2. Integration:
   • Hook into build process (e.g., after npm run dev or TYPO3’s typo3/sysext/core/Classes/ViewHelpers compilation).
3. Validation:
   • Run in CI first, then locally with a watcher (e.g., inotifywait for file changes).
4. Rollout:
   • Start with non-critical templates, then expand.

Operational Impact

Maintenance

• Rule Updates:
  • Custom rules require ongoing maintenance if Fluid syntax evolves (e.g., TYPO3 updates).
  • Document rule behavior in a RULES.md file for the team.
• Dependency Management:
  • Monitor Fractor’s monorepo for updates/abandonment.
  • Consider forking if the package stagnates.
• Configuration Drift:
  • Rules may need adjustment as template patterns change (e.g., new TYPO3 versions).

Support

• Debugging:
  • Limited community support (0 stars, no dependents). Debugging may require reverse-engineering Fractor’s core.
  • Log rule violations with context (e.g., line numbers, file paths) for easier triage.
• Onboarding:
  • Develop internal docs explaining:
    • How to write custom rules.
    • How to trigger Fractor (CLI, CI, etc.).
    • Example rule implementations.

Scaling

• Performance:
  • Large template sets may slow down processing. Optimize with:
    • Parallel processing (e.g., spatie/fork).
    • Caching (skip unchanged files via mtime checks).
  • Benchmark with 100+ templates to identify bottlenecks.
• Distributed Systems:
  • Not ideal for runtime template modification (e.g., live site edits). Use in staging/deployment.
  • For multi-server setups, run Fractor pre-deploy (e.g., in Envoyer’s before scripts).

Failure Modes

Ramp-Up

• Team Training:
  • 1-hour workshop on:
    • Fractor’s rule system.
    • Writing custom validators.
    • Interpreting output logs.
  • Assign a rule owner per team (e.g., frontend vs. backend).
• Phased Adoption:
  1. Week 1: Install and run basic checks.
  2. Week 2: Develop 1–2 custom rules.
  3. Week 3: Integrate into CI/CD.
  4. Week 4: Expand to all relevant templates.
• Metrics:
  • Track rule violation trends to refine standards.
  • Measure time saved in code reviews (e.g., fewer manual template checks).