Twigcs Laravel Package

Technical Evaluation

Architecture Fit

• Static Analysis Tooling: twigcs remains a Twig-specific linter/validator, maintaining its seamless fit for Laravel/PHP projects using Twig (standalone or via TwigBridge). The new release does not introduce architectural changes that would alter this fit.
• Complementary to Existing Stack:
  • Continues to integrate with CI/CD pipelines, PHPStan, and Twig extensions without disruption.
  • No Laravel-specific dependencies; remains non-invasive and standalone.
• Symfony Console Compatibility:
  • The fix for Symfony Console v8.0 (Application::add() method) ensures compatibility with modern Symfony/Laravel stacks using newer Symfony components (e.g., Laravel 10+ with Symfony 6.4+).

Integration Feasibility

• Low Coupling: Unchanged; still integrates via Composer without Laravel-specific dependencies.
• Configuration Flexibility:
  • No changes to .twigcs.yml or rule customization capabilities.
  • Backward-compatible with existing configurations.
• Output Formats: Unchanged (JSON, XML, text).

Technical Risk

• Symfony Console Dependency:
  • New Risk: Projects using Symfony Console <8.0 (e.g., older Laravel versions) may encounter deprecation warnings or require updates to symfony/console.
    • Mitigation: Pin symfony/console:^6.0 in composer.json if using Laravel <10 or Symfony <8.0.
  • Laravel 10+: No risk; Laravel 10 uses Symfony 6.4+, which is now supported.
• Rule Overlap: Unchanged; still requires auditing against existing tools (e.g., twiglint, phpstan).
• False Positives/Negatives: Unchanged; tuning via .twigcs.yml remains necessary.
• Performance Impact: Unchanged; no performance-related changes in this release.

Key Questions

1. Symfony Console Version:
   • What version of Symfony Console is used in the project?
     • If <8.0, pin symfony/console:^6.0 to avoid warnings.
     • If >=8.0, no action required.
2. Laravel Version:
   • Is the project using Laravel 10+ (Symfony 6.4+) or an older version?
     • Older versions may need symfony/console pinned.
3. Twig Usage Scope: (Unchanged from prior assessment)
   • Is Twig used standalone or via Blade? Does Blade require pre-processing?
4. CI/CD Integration: (Unchanged)
   • How will failures be handled in CI?
5. Rule Customization Needs: (Unchanged)
   • Are project-specific Twig patterns needed in .twigcs.yml?

Integration Approach

Stack Fit

• Primary Use Case: (Unchanged)
  • Twig template validation in Laravel/Symfony projects using Twig (standalone or TwigBridge).
• Secondary Use Case: (Unchanged)
  • Symfony/Lumen projects with Twig.
• Non-Fit: (Unchanged)
  • Pure Blade projects (unless hybrid Twig/Blade is adopted).
• Symfony Console Update:
  • Laravel 10+: No changes needed; fully compatible.
  • Laravel <10/Symfony <8.0: Requires pinning symfony/console:^6.0 to avoid deprecation warnings.

Migration Path

1. Assessment Phase: (Unchanged)
   • Run twigcs check --dry-run to identify issues.
2. Pilot Integration: (Updated for Symfony Console)
   • Add to composer.json:

     "require-dev": {
       "friendsoftwig/twigcs": "^6.6.1",
       "symfony/console": "^6.0"  // Only if using Symfony Console <8.0
     }
     

   • Configure .twigcs.yml with defaults.
3. CI/CD Onboarding: (Unchanged)
   • Add to .github/workflows/lint.yml:

     - name: Twig Lint
       run: vendor/bin/twigcs check --format=json > twigcs.json
     

4. Blade Workaround: (Unchanged)
   • Pre-process Blade files if needed (e.g., via custom script).

Compatibility

• Laravel-Specific: (Unchanged)
  • Works with TwigBridge or standalone Twig.
  • Blade: Requires manual handling.
• PHP Version: (Unchanged)
  • Supports PHP 8.1+.
• Twig Version: (Unchanged)
  • Supports Twig 2.x/3.x.
• Symfony Console: (Updated)
  • Requires Symfony Console >=6.0 (or pinned to ^6.0 for older versions).

Sequencing

1. Phase 1: Validate Twig templates in CI. (Unchanged)
2. Phase 2: Extend to Blade if critical. (Unchanged)
3. Phase 3: Customize rules and integrate with dashboards. (Unchanged)
4. Phase 4: Automate fixes. (Unchanged)

• New Step (if needed):
  • Phase 0: Update symfony/console to ^6.0 if using <8.0 (before integrating twigcs).

Operational Impact

Maintenance

• Rule Updates: (Unchanged)
  • Monitor for Twig syntax changes; update .twigcs.yml as needed.
• Dependency Management: (Updated)
  • Pin symfony/console if using versions <8.0:

    "require-dev": {
      "symfony/console": "^6.0"
    }
    

  • Update twigcs to ^6.6.1 in composer.json.
• Custom Rules: (Unchanged)
  • Maintain custom rule classes if extended.

Support

• Debugging: (Unchanged)
  • Use --verbose for details; check GitHub issues.
• Team Adoption: (Unchanged)
  • Provide runbooks for common errors.
  • Assign a linting champion.
• Symfony Console Warnings: (New)
  • If using Symfony Console <8.0, expect deprecation warnings until symfony/console is updated.

Scaling

• Performance: (Unchanged)
  • Lightweight; use parallel execution or incremental linting for large bases.
• Resource Usage: (Unchanged)
  • Minimal impact compared to PHPStan.

Failure Modes

Ramp-Up

• Onboarding Time: (Unchanged)
  • 1–3 days for setup (longer if Blade integration is needed).
• Training: (Unchanged)
  • Document common errors; share .twigcs.yml examples.
• Phased Rollout: (Unchanged)
  1. Lint only (no failures).
  2. Fail on warnings (after 2 weeks).
  3. Full enforcement (after 1 month).
• New Consideration:
  • Symfony Console Update: If using <8.0, add this as Phase 0 before integrating twigcs.