Switch from deprecated --set
option to ecs.php
config.
Switch YAML to PHP configuration.
Last year, I helped Shopsys Coding Standards and LMC PHP Coding Standard to migrate from PHP_CodeSniffer to ECS.
There are a few simple A → B changes, but one has to know about them or will get stuck.
Do you also use PHP_CodeSniffer and give it EasyCodingStandard a try? Today we look at how to migrate step by step.
ECS is a tool build on Symfony components that combines PHP_CodeSniffer and PHP CS Fixer. It's easy to use from scratch:
composer require symplify/easy-coding-standard --dev
ECS uses standard Symfony PHP config:
// ecs.php
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
use Symplify\EasyCodingStandard\ValueObject\Option;
use Symplify\EasyCodingStandard\ValueObject\Set\SetList;
return function (ContainerConfigurator $containerConfigurator): void {
$containerConfigurator->import(SetList::PSR_12);
};
And runs as CLI command:
vendor/bin/ecs check src
But what if you already have PHP_CodeSniffer on your project and want to switch?
You probably use string references to sniffs in your *.xml
configuration for PHP_CodeSniffer. You need to remember them, copy paste them and copy-paste them right.
<!-- phpcs.xml -->
<rule ref="Generic.Commenting.DocComment"/>
That can actually cause typos like:
-<rule ref="Generic.Commenting.DocComment"/>
+<rule ref="Generic.Commenting.DocComment"/>
How to do that in EasyCodingStandard? Copy paste the last name DocComment
and add rule in set()
method. Hit CTRL + Space and PHPStorm will autocomplete class for you:
// ecs.php
use PHP_CodeSniffer\Standards\Generic\Sniffs\Commenting\DocCommentSniff;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
return function (ContainerConfigurator $containerConfigurator): void {
$services = $containerConfigurator->services();
$services->set(DocCommentSniff::class);
};
No more typos with strong over string typing.
@codingStandardsIgnoreStart
to skip
ParameterIf you'd like to skip nasty code from being analyzed, you'd use @codingStandardsIgnoreStart
in PHP_CodeSniffer.
# packages/framework/src/Component/Constraints/EmailValidator.php
private function isEmail($value)
{
// @codingStandardsIgnoreStart
$atom = "[-a-z0-9!#$%&'*+/=?^_`{|}~]"; // RFC 5322 unquoted characters in local-part
// @codingStandardsIgnoreEnd
}
One big cons of this is that all sniffs will skip this code, not just one. So even if here we need to only allow double quotes "
, all other checks will miss it.
To skip this in EasyCodingStandard just use skip
parameter:
// ecs.php
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
use Symplify\EasyCodingStandard\ValueObject\Option;
use PHP_CodeSniffer\Standards\Squiz\Sniffs\Strings\DoubleQuoteUsageSniff;
return function (ContainerConfigurator $containerConfigurator): void {
$parameters = $containerConfigurator->parameters();
$parameters->set(Option::SKIP, [
DoubleQuoteUsageSniff::class => [
__DIR__ . '/packages/framework/src/Component/Constraints/EmailValidator.php',
// or whole directory
__DIR__ . '/packages/framework/src/Component',
// or for mask directory
__DIR__ . '/packages/*/src/Component',
]
]);
};
<severity>0</severity>
and <exclude name="...">
to skip
ParameterDo you need to skip only 1 part of the sniff? In PHP_CodeSniffer:
<rule ref="Generic.Commenting.DocComment.ContentAfterOpen">
<severity>0</severity>
</rule>
or
<rule ref="Generic.Commenting.DocComment">
<exclude name="Generic.Commenting.DocComment.ContentAfterOpen"/>
</rule>
In EasyCodingStandard, we put that again under skip
parameter in format <Sniff>.<CodeName>
:
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
use Symplify\EasyCodingStandard\ValueObject\Option;
use PHP_CodeSniffer\Standards\Generic\Sniffs\Commenting\DocCommentSniff;
return function (ContainerConfigurator $containerConfigurator): void {
$parameters = $containerConfigurator->parameters();
$parameters->set(Option::SKIP, [
DocCommentSniff::class . '.ContentAfterOpen' => null,
]);
};
For all other skip
options, see README.
In case you need to skip the whole sniff:
<?xml version="1.0" encoding="UTF-8"?>
<ruleset name="ruleset">
<rule ref="Generic.Commenting.DocComment">
<severity>0</severity>
</rule>
</ruleset>
or
<?xml version="1.0" encoding="UTF-8"?>
<ruleset name="ruleset">
<rule ref="ruleset.xml">
<exclude name="Generic.Commenting.DocComment"/>
</rule>
</ruleset>
Put it under skip
parameter:
use PHP_CodeSniffer\Standards\Generic\Sniffs\Commenting\DocCommentSniff;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
use Symplify\EasyCodingStandard\ValueObject\Option;
return function (ContainerConfigurator $containerConfigurator): void {
$parameters = $containerConfigurator->parameters();
$parameters->set(Option::SKIP, [
DocCommentSniff::class => null,
]);
};
These names are looked for in the root directory by PHP_CodeSniffer:
- .phpcs.xml
- phpcs.xml
- .phpcs.xml.dist
- phpcs.xml.dist
And by ECS just plain ecs.php
PHP file
What about non-default locations or names?
From:
vendor/bin/phpcs /path/to/project --standard=custom/location.xml
to:
vendor/bin/ecs check /path/to/project --config custom/location.php
From XML configuration in PHP_CodeSniffer:
<?xml version="1.0" encoding="UTF-8"?>
<ruleset name="ruleset">
<rule ref="Generic.Metrics.CyclomaticComplexity">
<properties>
<property name="complexity" value="13"/>
<property name="absoluteComplexity" value="13"/>
</properties>
</rule>
</ruleset>
to PHP parameters in ECS:
<?php
declare(strict_types=1);
// ecs.php
use PHP_CodeSniffer\Standards\Generic\Sniffs\Metrics\CyclomaticComplexitySniff;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
return function (ContainerConfigurator $containerConfigurator): void {
$services = $containerConfigurator->services();
$services->set(CyclomaticComplexitySniff::class)
->property('complexity', 13)
->property('absoluteComplexity', 13);
};
There are different levels in PHP_CodeSniffer. You can set severity, make sniff report as warning or as an error.
<?xml version="1.0" encoding="UTF-8"?>
<ruleset name="ruleset">
<rule ref="Generic.Commenting.DocComment">
<severity>5</severity>
</rule>
</ruleset>
This complex matrix leveling lead to confused questions for many people:
And so on.
Thus these confusing options are not supported and EasyCodingStandard simplifies that to errors only CI server either passes or not. The rule is required and respected or removed. Simple, clear and without any confusion.
Saying that you don't need to fill values for warning properties.
--fix
optionDo you need to fix the code? From 2 commands in PHP_CodeSniffer:
vendor/bin/phpcs /path/to/project --standard=custom/location.xml
vendor/bin/phpcbf /path/to/project --standard=custom/location.xml
to 1 in EasyCodingStandard:
vendor/bin/ecs check /path/to/project --config custom/location.php
vendor/bin/ecs check /path/to/project --config custom/location.php --fix
...and you won't regret it. Sylius, PestPHP, LMC, Shopsys, Nette did and never came back.
Did I forget a step that you had to fight with? Please, let me know in the comments or just send PR to this post to add it, so we help other readers.
In the next post we look on how to migrate from PHP CS Fixer!
Do you learn from my contents or use open-souce packages like Rector every day?
Consider supporting it on GitHub Sponsors.
I'd really appreciate it!