The missing checkstyle for twig!
Twigcs aims to be what phpcs is to php. It checks your codebase for violations on coding standards.
composer global require friendsoftwig/twigcs
Basically, just run:
twigcs /path/to/views
On Symfony projects, you can run, for instance:
twigcs /project/dir/app/Resources/views
You will get a summary of the violations in the console. The exit code of the command is based on the severity of any violation found. By default, twigcs only tolerates notices, this can be changed at run time:
twigcs /path/to/views --severity error # Allows notices and warnings
twigcs /path/to/views --severity notice # Disallows notices
twigcs /path/to/views --severity ignore # Allows everything
With the example above, notices are still displayed but not altering the exit code.
You can also exclude relative subfolders of path like this:
twigcs /path/to/views --exclude vendor
Tips: You can use multiple exclude parameters.
By default TwigCS will output all lines that have violations regardless of whether they match the severity level
specified or not. If you only want to see violations that are greater than or equal to the severity level you've specified
you can use the --display
option. For example.
twigcs /path/to/views --severity error --display blocking
Would only display errors and not warnings.
Alternatively you can use --display all
which is the default behaviour as described above.
Twigcs can be used with your favorite CI server. The command itself will return a consistent exit code telling the CI job if it failed or succeeded. You can also have a nice xml report (checkstyle format):
twigcs /path/to/views --reporter checkstyle > /path/to/report.xml
By default twigcs is using Twig 3. This means that features like filter
tags or filtered loops using if
are not supported
anymore. You can use an older twig version using the twig-version
option:
twigcs /path/to/views --twig-version 2
At the moment the only available standard is the official one from twig.
You can create a class implementing RulesetInterface
and supply it as a --ruleset
option to the CLI script:
twigcs /path/to/views --ruleset \MyApp\TwigCsRuleset
Note: twigcs
needs to be used via composer and the ruleset class must be reachable via composer's autoloader for this feature to work.
Also note that depending on your shell, you might need to escape backslashes in the fully qualified class name:
twigcs /path/to/views --ruleset \\MyApp\\TwigCsRuleset
For more complex needs, have a look at the custom ruleset documentation.
Using configuration, you can easily store per-project settings:
// ~/.twig_cs.dist
<?php
return \FriendsOfTwig\Twigcs\Config\Config::create()
->setName('my-config')
->setSeverity('warning')
->setReporter('json')
->setRuleSet(FriendsOfTwig\Twigcs\Ruleset\Official::class)
->setSpecificRuleSets([ // Every file matching the pattern will use a different ruleset.
'*/template.html.twig' => Acme\Project\CustomRuleset::class,
])
;
This configuration will be applied if you call twigcs from the ~/
directory. If you run twigcs from outside this directory,
you must use the --config
option:
cd ~/dirA
twigcs --config ~/dirB/.twig_cs.dist # Will lint templates in ~/dirA with the config of ~/dirB
By default, the files .twig_cs
and .twig_cs.dist
are looked up in your current working directory (CWD).
You can also provide finders inside config files, they will completely replace the path in the CLI:
// ~/.twig_cs.dist
<?php
$finderA = FriendsOfTwig\Twigcs\Finder\TemplateFinder::create()->in(__DIR__.'/dirA');
$finderB = FriendsOfTwig\Twigcs\Finder\TemplateFinder::create()->in(__DIR__.'/dirB');
return \FriendsOfTwig\Twigcs\Config\Config::create()
// ...
->addFinder($finderA)
->addFinder($finderB)
->setName('my-config')
;
In this case, calling twigcs
from the ~/
directory of the config will run the linter on the directories pointed by the finders.
If you explicitly supply a path to the CLI, it will be added to the list of linted directories:
twigcs ~/dirC # This will lint ~/dirA, ~/dirB and ~/dirC using the configuration file of the current directory.
If you're upgrading from 3.x to 4.x or later, please read the upgrade guide.
Join us on Symfony Devs via the twigcs channel.
The master is the development branch, if you find any bug or false positive during style checking, please open an issue or submit a pull request.
When creating or changing a class, don't forget to add you as an @author
at the top of the file.