How to Migrate From PHP_CodeSniffer to EasyCodingStandard in 7 Steps

This post was updated at August 2020

Updated ECS YAML to PHP configuration since ECS 8.


Last year, I helped Shopsys Coding Standards and LMC PHP Coding Standard to migrate from PHP_CodeSniffer to EasyCodingStandard.

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 3.4 components that combines PHP_CodeSniffer and PHP CS Fixer. It's super easy to start to use from scratch:

composer require symplify/easy-coding-standard --dev
vendor/bin/ecs check src --set psr12

But what if you already have PHP_CodeSniffer on your project and want to switch?

1. From String Codes to Autocompleted Classes

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.Comenting.DocComment"/>

That can actually cause typos like:

-<rule ref="Generic.Comenting.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:

<?php

// ecs.php

declare(strict_types=1);

use PHP_CodeSniffer\Standards\Generic\Sniffs\Commenting\DocCommentSniff;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $containerConfigurator): void {
    $services = $containerConfigurator->services();
    $services->set(DocCommentSniff::class);
};

No more typos with strong over string typing.

2. From @codingStandardsIgnoreStart to skip Parameter

If 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:

<?php

// ecs.php

declare(strict_types=1);

use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
use Symplify\EasyCodingStandard\Configuration\Option;
use PHP_CodeSniffer\Standards\Squiz\Sniffs\Strings\DoubleQuoteUsageSniff;

return static 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',
        ]
    ]);
};

3. From <severity>0</severity> and <exclude name="..."> to skip Parameter

Do 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>:

<?php

// ecs.php

declare(strict_types=1);

use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
use Symplify\EasyCodingStandard\Configuration\Option;
use PHP_CodeSniffer\Standards\Generic\Sniffs\Commenting\DocCommentSniff;

return static 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:

<?php

// ecs.php

declare(strict_types=1);

use PHP_CodeSniffer\Standards\Generic\Sniffs\Commenting\DocCommentSniff;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
use Symplify\EasyCodingStandard\Configuration\Option;

return static function (ContainerConfigurator $containerConfigurator): void {
    $parameters = $containerConfigurator->parameters();

    $parameters->set(Option::SKIP, [
        DocCommentSniff::class => null,
    ]);
};

4. From XML to PHP Config Paths

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

5. Configuring Sniff Values

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 static function (ContainerConfigurator $containerConfigurator): void {
    $services = $containerConfigurator->services();

    $services->set(CyclomaticComplexitySniff::class)
        ->property('complexity', 13)
        ->property('absoluteComplexity', 13);
};

6. From Severity and Warning to Just Errors

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.

7. From Beautifier to --fix option

Do 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


Give it a Try...

...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!