Twig Cs Fixer Laravel Package

Technical Evaluation

Architecture Fit

• Laravel/Twig Integration: The package is highly relevant for Laravel projects using Twig (e.g., via twig/bridge or spatie/laravel-twig). It enforces Twig-specific coding standards, complementing PHP-CS-Fixer for backend logic.
• Modularity: Works alongside existing tools (e.g., PHP-CS-Fixer, ESLint) without disrupting Laravel’s templating pipeline. Can be integrated into CI/CD (e.g., GitHub Actions, GitLab CI) for automated linting.
• Extensibility: Supports custom rules, Twig extensions, and node visitors, enabling alignment with project-specific conventions (e.g., domain-specific naming rules).

Integration Feasibility

• Low Friction: Installs via Composer (--dev dependency) and integrates seamlessly with Laravel’s vendor/bin CLI tools.
• Configuration Flexibility: Customizable via .twig-cs-fixer.php (parallel to Laravel’s .php-cs-fixer.dist.php), allowing granular control over rules (e.g., disabling VariableNameRule for legacy templates).
• Cache Optimization: Built-in caching (--no-cache flag) reduces CI/CD overhead, critical for large template repos.

Technical Risk

• Dependency Conflicts: Risk of PHP version mismatches (package requires PHP 8.1+; Laravel 9+ is compatible). Mitigate via composer.json constraints.
• Twig Version Lock: Rules like NamedArgumentSeparatorRule require Twig ≥3.12.0. Audit Laravel’s Twig version (twig/twig) before adoption.
• False Positives: Non-fixable rules (e.g., FileNameRule) may flag legitimate legacy templates. Requires explicit whitelisting in config.
• Performance: Heavy template repos may experience slow linting due to Twig parsing. Test with --dry-run first.

Key Questions

1. Twig Usage Scope:
   • Is Twig used for all templates (e.g., Blade alternatives) or partials only? Adjust Finder config accordingly.
   • Are templates auto-generated (e.g., by APIs)? Exclude dynamic paths from linting.
2. CI/CD Integration:
   • Should linting block merges (fail-fast) or warn only? Configure via --report=github/--report=gitlab.
3. Rule Customization:
   • Are project-specific naming conventions (e.g., PascalCase variables) needed? Override VariableNameRule or NamedArgumentNameRule.
4. Legacy Code:
   • What % of templates are non-compliant? Prioritize fixes via --allow-risky=yes or phased rollouts.
5. Toolchain Synergy:
   • How does this interact with existing tools (e.g., PHP-CS-Fixer, Blade analyzers)? Define a linting order (e.g., PHP → Twig → Blade).

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Primary Use Case: Enforce Twig standards in projects using spatie/laravel-twig or custom Twig setups.
  • Secondary Use Case: Complement PHP-CS-Fixer for full-stack consistency (e.g., php-cs-fixer for PHP, twig-cs-fixer for templates).
• Toolchain Placement:
  • CI/CD: Run as a pre-commit hook (via laravel-pint or roave/security-advisories) or post-merge check (GitHub Actions).
  • Local Dev: Integrate with Laravel Forge or Laravel Valet for real-time feedback (e.g., via twig-cs-fixer lint --report=text).
• IDE Support:
  • Pair with PHPStorm’s Twig plugin or VSCode’s Twig extension for on-save formatting (if rules are fixable).

Migration Path

1. Pilot Phase:
   • Scope: Start with a single template directory (e.g., resources/views).
   • Command: vendor/bin/twig-cs-fixer lint --dry-run resources/views → Review output.
   • Fix: vendor/bin/twig-cs-fixer fix --allow-risky=yes resources/views.
2. Configuration:
   • Create .twig-cs-fixer.php with project-specific rules (e.g., override snake_case for kebab-case variables).
   • Example:

     $ruleset->overrideRule(new TwigCsFixer\Rules\Naming\VariableNameRule('kebab-case'));
     

3. CI/CD Rollout:
   • Add to .github/workflows/lint.yml:

     - name: Twig Lint
       run: vendor/bin/twig-cs-fixer lint --report=github --config=.twig-cs-fixer.php resources/views
     

   • Fail Fast: Set if: always() and require success() for PRs.
4. Full Adoption:
   • Expand to all Twig templates (e.g., storage/framework/views if cached).
   • Document exceptions in docs/CODING_STANDARDS.md.

Compatibility

• Laravel Versions:
  • Supported: Laravel 9+ (PHP 8.1+). For older versions, use the PHAR (e.g., twig-cs-fixer.phar).
  • Workaround: Pin Twig version in composer.json:

    "require": {
      "twig/twig": "^3.12"
    }
    

• Blade Hybrid Projects:
  • Exclude Blade files via Finder:

    $finder->exclude('*.blade.php');
    

• Monorepos:
  • Use --config to scope rules per project (e.g., --config=packages/app/.twig-cs-fixer.php).

Sequencing

1. Pre-Requirements:
   • Audit Twig version (composer show twig/twig).
   • Backup templates (e.g., git checkout -- resources/views).
2. Toolchain Order:
   • Step 1: Run PHP-CS-Fixer (backend logic).
   • Step 2: Run twig-cs-fixer (templates).
   • Step 3: Run Blade analyzers (if applicable).
3. Post-Integration:
   • Add to composer.json scripts:

     "scripts": {
       "lint:twig": "twig-cs-fixer lint --report=text",
       "fix:twig": "twig-cs-fixer fix"
     }
     

Operational Impact

Maintenance

• Rule Updates:
  • Automatic: Dependabot alerts for vincentlanglet/twig-cs-fixer updates.
  • Manual: Review changelog for breaking changes (e.g., new Twig version requirements).
• Configuration Drift:
  • Store .twig-cs-fixer.php in version control (not .gitignore).
  • Use .dist files for team-specific overrides (e.g., .twig-cs-fixer.dist.php).
• Deprecation:
  • Monitor for end-of-life (last release: 2026-06-29; check for updates post-2027).

Support

• Troubleshooting:
  • Common Issues:
    • Class not found: Run composer dump-autoload.
    • Twig version mismatch: Update twig/twig or use PHAR.
    • Permission denied: Set cache dir to /tmp/.twig-cs-fixer.cache.
  • Debugging: Use --verbose flag or enable custom reporters for logs.
• Team Onboarding:
  • Documentation: Add a linting guide in docs/ with:
    • Example config snippets.
    • Excluded paths (e.g., vendor/, node_modules/).
    • How to opt out of rules (e.g., @twig-cs-fixer:disable comments).
  • Training: Demo the --fix command in a team workshop.

Scaling

• Performance:
  • Large Repos: Use --parallel (if supported) or split by directory:

    twig-cs-fixer lint resources/views/{admin,public} --parallel
    

  • CI Timeouts: Cache results (--cache) or use GitHub Actions caching:

    - uses: actions/cache@v3
      with:
        path: ~/.twig-cs-fixer.cache
        key: twig-cs-fixer-${{ hashFiles('.twig-cs-fixer.php') }}
    

• Distributed Teams: