Getting Started

Minimal Steps

Installation:

composer require --dev vincentlanglet/twig-cs-fixer

Ensure bin-dependencies is enabled in your composer.json:

"config": {
    "bin-dir": "bin",
    "bin-dependencies": true
}

First Run (Linting):
```
vendor/bin/twig-cs-fixer lint resources/views
```
This checks Twig files in resources/views for coding standard violations.
First Fix:
```
vendor/bin/twig-cs-fixer fix resources/views
```
Automatically applies fixes to non-compliant files.

Where to Look First

Default Rules: The package enforces Twig’s official coding standards by default (e.g., snake_case variables, delimiter spacing).
Configuration File: Create .twig-cs-fixer.php in your project root to customize rules (see Implementation Patterns).
CLI Help:
```
vendor/bin/twig-cs-fixer --help
```
Lists all available commands, reporters, and options.

First Use Case: Pre-Commit Hook

Integrate twig-cs-fixer into your workflow to enforce consistency before commits:

# Add to package.json (if using Laravel Mix)
"scripts": {
    "lint:twig": "twig-cs-fixer lint resources/views"
}

Or use a tool like Husky to run it automatically.

Implementation Patterns

Workflows

1. Project-Wide Enforcement

Configuration: Extend the default ruleset in .twig-cs-fixer.php:

<?php
$ruleset = new \TwigCsFixer\Ruleset\Ruleset();
$ruleset->addStandard(new \TwigCsFixer\Standard\TwigCsFixer());
$ruleset->overrideRule(new \TwigCsFixer\Rules\Whitespace\EmptyLinesRule(2)); // 2 lines between blocks

$config = new \TwigCsFixer\Config\Config();
$config->setRuleset($ruleset);
return $config;

Run:

vendor/bin/twig-cs-fixer fix resources/views --config=.twig-cs-fixer.php

2. Team-Specific Rules

Custom Rules: Disable SingleQuoteRule for legacy projects:

$ruleset->removeRule(\TwigCsFixer\Rules\String\SingleQuoteRule::class);

File-Specific Ignores: Use .twig-cs-fixer.dist.php for team defaults and .twig-cs-fixer.php for overrides.

3. CI/CD Integration

GitHub Actions Example:

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

Outputs annotations for failed checks.

4. Partial Fixes

Fix only specific files/directories:
```
vendor/bin/twig-cs-fixer fix resources/views/partials --dry-run
```
Use --dry-run to preview changes.

Integration Tips

Laravel-Specific

Service Provider: Register the fixer as a Laravel command:

// app/Console/Commands/FixTwigCommand.php
namespace App\Console\Commands;
use TwigCsFixer\Application;

class FixTwigCommand extends Command {
    protected $signature = 'twig:fix';
    public function handle() {
        $app = new Application();
        $app->run(['fix', 'resources/views']);
    }
}

Add to app/Console/Kernel.php:

protected $commands = [
    \App\Console\Commands\FixTwigCommand::class,
];

Run with:

php artisan twig:fix

IDE Integration

PHPStorm: Use the External Tools settings to run twig-cs-fixer on save:
- Program: vendor/bin/twig-cs-fixer
- Arguments: fix $FilePath$
- Working Directory: $ProjectFileDir$

Custom Rules

Extend Rules: Create a custom rule by extending AbstractRule:

namespace App\Rules;
use TwigCsFixer\Rule\AbstractRule;

class CustomBlockRule extends AbstractRule {
    public function getName() {
        return 'custom_block_rule';
    }
    public function process(\TwigCsFixer\File $file) {
        // Custom logic
    }
}

$ruleset->addRule(new \App\Rules\CustomBlockRule());

Gotchas and Tips

Pitfalls

Cache Issues:
- Problem: Cache may retain old rule configurations if the PHP version or package version changes.
- Fix: Clear cache with --no-cache or set null in config:
```
$config->setCacheFile(null);
```
Non-Fixable Rules:
- Problem: Rules like FileNameRule are non-fixable by default and may cause lint failures without fixes.
- Fix: Explicitly allow non-fixable rules:
```
$config->allowNonFixableRules();
```
Twig Version Mismatch:
- Problem: Node-based rules may fail if your Twig version doesn’t support the required AST nodes.
- Fix: Check Twig CS Fixer’s compatibility matrix and update Twig:
```
composer require twig/twig:^3.12
```
Overly Strict Rules:
- Problem: Rules like SingleQuoteRule may break legacy templates with escaped single quotes.
- Fix: Configure exceptions:
```
$ruleset->overrideRule(new \TwigCsFixer\Rules\String\SingleQuoteRule([
    'skipStringContainingSingleQuote' => false,
]));
```
Performance:
- Problem: Large projects may slow down due to cache or complex rules.
- Fix: Limit scope or disable cache temporarily:
```
vendor/bin/twig-cs-fixer lint resources/views --no-cache
```

Debugging

Dry Runs: Use --dry-run to preview changes without modifying files:
```
vendor/bin/twig-cs-fixer fix --dry-run
```
Verbose Output: Enable debug mode for detailed logs:
```
vendor/bin/twig-cs-fixer lint --verbose
```
Rule-Specific Debugging: Isolate rule failures by testing individual rules:
```
vendor/bin/twig-cs-fixer lint --rules=DelimiterSpacingRule
```
Custom Reporter: Use junit or github reporters for CI debugging:
```
vendor/bin/twig-cs-fixer lint --report=junit > report.xml
```

Tips

Partial Fixes: Use --path-mode=union to fix only files that violate rules:
```
vendor/bin/twig-cs-fixer fix --path-mode=union
```

Exclude Files: Configure the Finder to skip specific files/directories:

$finder = new \TwigCsFixer\File\Finder();
$finder->in('resources/views')->exclude(['legacy', 'vendor']);
$config->setFinder($finder);

Symfony Integration: Combine with symfony/coding-standard for PHP/Twig consistency:

composer require --dev symfony/coding-standard
vendor/bin/ecs check src resources/views

Custom Token Parsers: Extend Twig’s token parsing for custom syntax (e.g., Laravel Blade-like directives):
```
$config->addTokenParser(new \App\Twig\CustomTokenParser());
```

Git Pre-Commit: Use twig-cs-fixer in a pre-commit hook via PHP-CS-Fixer’s pre-commit example:

# .git/hooks/pre-commit
#!/bin/sh
vendor/bin/twig-cs-fixer fix resources/views --allow-risky=yes

IDE Formatting: Configure your IDE to trigger twig-cs-fixer on save (e.g., PHPStorm’s onSave actions).
**Leg

Twig Cs Fixer Laravel Package