How to Migrate From PHP_CodeSniffer to ECS in 7 Steps

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?

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

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:

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

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

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

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

• Is it a warning or is an accepted error?
• What is this warning even active when it doesn't fail CI?
• Why do we have an accepted error - is it like the tests that are allowed to fail?

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!