Twigcs Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require --dev friendsoftwig/twigcs
   

   Add to your project's composer.json under require-dev if not already present.

2. Basic CLI Usage Run TwigCS directly on a template file:

   vendor/bin/twigcs path/to/template.twig
   

   Or integrate into a CI pipeline (e.g., GitHub Actions) for automated checks.

3. First Use Case Validate a single Twig template for common issues (e.g., unused variables, deprecated tags):

   vendor/bin/twigcs templates/partials/header.twig
   

   Output will list violations with line numbers and severity.

Implementation Patterns

Workflow Integration

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

   "scripts": {
     "test": [
       "@test-unit",
       "twigcs --no-interaction templates/**/*.twig"
     ]
   }
   

   Fail builds on violations with --no-interaction (exit code 1 on errors).

2. Symfony 8.0+ Compatibility With v6.6.1, TwigCS now supports Symfony 8.0's updated Console component. For Symfony projects, ensure your twigcs.yaml config remains unchanged:

   twigcs:
     paths: ["templates/"]
     config: "%kernel.project_dir%/config/twigcs.json"
   

   Run via Symfony CLI:

   php bin/console twigcs:check
   

3. IDE/Editor Integration

   • Use twigcs as a custom linting tool in PHPStorm/VSCode via:
     • PHPStorm: Settings > Languages & Frameworks > PHP > Code Sniffer (add custom tool).
     • VSCode: Configure php-cs-fixer extension to run twigcs via settings.json.

4. Custom Rulesets Extend default rules by creating a twigcs.json config:

   {
     "rules": {
       "TwigCS.Rules.UnusedVariable": {
         "severity": "warning"
       },
       "TwigCS.Rules.DeprecatedTag": {
         "severity": "error"
       }
     }
   }
   

   Run with:

   vendor/bin/twigcs --config=path/to/twigcs.json templates/
   

Gotchas and Tips

Pitfalls

1. Symfony 8.0 Console Compatibility

   • Issue: Projects using Symfony 8.0+ may encounter FatalError if not using v6.6.1+.
   • Fix: Update TwigCS to v6.6.1 or later:

     composer update friendsoftwig/twigcs --dev
     

2. False Positives

   • Issue: Rules like UnusedVariable may flag variables used dynamically (e.g., {% if var in someArray %}).
   • Fix: Whitelist variables in twigcs.json:

     "TwigCS.Rules.UnusedVariable": {
       "ignoreVariables": ["_context", "loop"]
     }
     

3. Performance

   • Issue: Scanning large template directories (**/*.twig) can be slow.
   • Fix: Use --parallel for multi-core processing:

     vendor/bin/twigcs --parallel templates/
     

4. Deprecated Tags

   • Issue: twigcs may flag tags as deprecated even if your Twig version supports them.
   • Fix: Override severity in config or suppress with --ignore-errors.

Debugging Tips

• Verbose Output: Use --verbose to see skipped files/rules:

  vendor/bin/twigcs --verbose templates/
  

• Dry Run: Test config changes without fixing:

  vendor/bin/twigcs --dry-run
  

• Rule Documentation: List all rules with descriptions:

  vendor/bin/twigcs --list-rules
  

Extension Points

1. Custom Rules Extend TwigCS by creating a TwigCS\Rule\AbstractRule subclass. Example:

   namespace App\TwigCS\Rules;
   use TwigCS\Rule\AbstractRule;
   
   class CustomRule extends AbstractRule {
       public function getName() { return 'CustomRule'; }
       public function getDescription() { return 'Checks for custom patterns.'; }
       public function process(Node $node, TwigEnvironment $env) {
           // Custom logic here
       }
   }
   

   Register in twigcs.json:

   "customRules": ["App\\TwigCS\\Rules\\CustomRule"]
   

2. Pre/Post-Processing Hook into TwigCS events via service providers (Symfony) or CLI arguments:

   vendor/bin/twigcs --pre-process="App\\TwigCS\\PreProcessor"
   

3. Integration with PHP-CS-Fixer Use easy-coding-standard to combine TwigCS with PHP-CS-Fixer:

   composer require --dev easy-coding-standard
   vendor/bin/ecs check src templates --config=ecs.php
   

   Configure ecs.php:

   return [
       'rules' => [
           \Squizlabs\PHP_Codesniffer\Ruleset::register('TwigCS'),
       ],
   ];