alec-liu / EasyCodingStandard

[READ-ONLY] Easiest way to start using PHP CS Fixer and PHP_CodeSniffer with 0-knowledge

The Easiest Way to Use Any Coding Standard

Used by:

Features

• Use PHP_CodeSniffer || PHP-CS-Fixer - anything you like
• 2nd run under few seconds with caching
• Skipping files for specific checkers
• Prepared checker sets - PSR2, Symfony, Common, Symplify and more...

Are you already using another tool?

• How to Migrate From PHP_CodeSniffer to EasyCodingStandard in 7 Steps
• How to Migrate From PHP CS Fixer to EasyCodingStandard in 6 Steps

Install

composer require --dev symplify/easy-coding-standard

Usage

1. Create Configuration and Setup Checkers

Create an easy-coding-standard.yaml in your root directory and add Sniffs or Fixers you'd love to use.

Let's start with the most common one - array() => []:

services:
    PhpCsFixer\Fixer\ArrayNotation\ArraySyntaxFixer:
        syntax: short

2. Run in CLI

# dry
vendor/bin/ecs check src

# fix
vendor/bin/ecs check src --fix

Tip: Do you want autocomplete too? Just use Symfony Plugin

More Features

Use Prepared Checker Sets

There are prepared sets in /config/set directory that you can use:

• clean-code.yaml
• common.yaml
• php71.yaml
• psr2.yaml
• ...

You pick config in CLI with --config:

vendor/bin/ecs check src --config vendor/symplify/easy-coding-standard/config/set/clean-code.yaml

Too long? Try --level shortcut:

vendor/bin/ecs check src --level clean-code

or include more of them in config:

# easy-coding-standard.yaml
imports:
    - { resource: 'vendor/symplify/easy-coding-standard/config/set/clean-code.yaml' }
    - { resource: 'vendor/symplify/easy-coding-standard/config/set/psr2.yaml' }

In case of custom coding standard and include e.g. psr2.yaml form this package, you might want to use %vendor_dir% or %current_working_dir% for:

# lmc-coding-standard.yaml
imports:
    - { resource: '%vendor_dir%/symplify/easy-coding-standard/config/set/psr2.yaml' }
    # or
    - { resource: '%current_working_dir%/vendor/symplify/easy-coding-standard/config/set/psr2.yaml' }

That would load file always from vendor dir, no matter where you are.

Exclude Checkers

What if you add symfony.yaml set, but don't like PhpCsFixer\Fixer\PhpTag\BlankLineAfterOpeningTagFixer?

imports:
    - { resource: 'vendor/symplify/easy-coding-standard/config/set/symfony.yaml' }

parameters:
    skip:
        PhpCsFixer\Fixer\PhpTag\BlankLineAfterOpeningTagFixer: ~

Include Checkers Only for Some Paths

This feature is the exact opposite of skip. Do you want to run your rule only on new code? Limit it with only parameter:

services:
    Symplify\CodingStandard\Sniffs\Naming\AbstractClassNameSniff: ~

parameters:
    only:
        Symplify\CodingStandard\Sniffs\Naming\AbstractClassNameSniff:
            - 'src/NewCode/*'

Ignore What You Can't Fix

Sometimes, checker finds an error in code that inherits from code you can't change.

No worries! Just skip checker for this file:

parameters:
    skip:
        SlevomatCodingStandard\Sniffs\TypeHints\TypeHintDeclarationSniff:
            # relative path to file (you can copy this from error report)
            - 'packages/EasyCodingStandard/packages/SniffRunner/src/File/File.php'

            # or multiple files by path to match against "fnmatch()"
            - '*packages/CodingStandard/src/Sniffs/*/*Sniff.php'

You can also skip specific codes or messages that you know from PHP_CodeSniffer:

parameters:
    skip:
        # code to skip for all files
        SlevomatCodingStandard\Sniffs\TypeHints\TypeHintDeclarationSniff.UselessDocComment: ~

        # same syntax is used for skipping specific sniff messages
        'Cognitive complexity for method "addAction" is 13 but has to be less than or equal to 8.': ~

        # code to skip for specific files/patterns
        SlevomatCodingStandard\Sniffs\TypeHints\TypeHintDeclarationSniff.MissingTraversableParameterTypeHintSpecification:
            -  '*src/Form/Type/*Type.php'

Or just 2 files?

parameters:
    exclude_files:
        # generated files
        - 'lib/PhpParser/Parser/Php5.php'
        - 'lib/PhpParser/Parser/Php7.php'
        # or with fnmatch() pattern
        - '*/lib/PhpParser/Parser/Php*.php'

Do you need to Include tests, *.php, *.inc or *.phpt files?

Normally you want to exclude these files, because they're not common code - they're just test files or dummy fixtures. In case you want to check them as well, you can.

Let's say you want to include *.phpt files.

• Create a class in src/Finder/PhpAndPhptFilesProvider.php

• Implement Symplify\EasyCodingStandard\Contract\Finder\CustomSourceProviderInterface

• Register it as services to easy-coding-standard.yaml like any other Symfony service:

  services:
      App\Finder\PhpAndPhptFilesProvider: ~

The PhpAndPhptFilesProvider might look like this:

namespace App\Finder;

use IteratorAggregate;
use Nette\Utils\Finder;
use SplFileInfo;
use Symplify\EasyCodingStandard\Contract\Finder\CustomSourceProviderInterface;

final class PhpAndPhptFilesProvider implements CustomSourceProviderInterface
{
    /**
     * @param string[] $source
     * @return mixed[]
     */
    public function find(array $source)
    {
        # $source is "source" argument passed in CLI
        # inc CLI: "vendor/bin/ecs check /src" => here: ['/src']
        return Finder::find('*.php', '*.phpt')->in($source);
    }
}

Don't forget to autoload it with composer.

Use any Finder you like: Nette\Finder or Symfony\Finder. You can also return array of files or SplFileInfos.

FAQ

How can I see all loaded checkers?

vendor/bin/ecs show
vendor/bin/ecs show --config ...

How do I find checkers by group or type?

vendor/bin/ecs find
vendor/bin/ecs find symplify # for Symplify rules
vendor/bin/ecs find array # for array-related rules

How do I clear cache?

vendor/bin/ecs check src --clear-cache

How can I change the cache directory?

parameters:
    cache_directory: .ecs_cache # defaults to sys_get_temp_dir() . '/_easy_coding_standard/_changed_files_detector_tests'

How can I change the cache namespace?

parameters:
    cache_namespace: my_project_namespace # defaults to Strings::webalize(getcwd())'

This comes in handy when you want to apply ecs caching mechanism on your gitlab pipelines for example, where getcwd() may not always produce same cache key, thus introducing side effect, where cache may not be detected correctly.

Example getcwd() on gitlab CI:

• /builds/0956d275/0/sites/my_project
• /builds/0956d275/1/sites/my_project
• /builds/0956d275/2/sites/my_project

Can I use tabs, 2 spaces or "\r\n" line endings?

parameters:
    indentation: "tab" # "spaces" by default, you can also use "  " (2 spaces), "    " (4 spaces) or "	" (tab)
    line_ending: "\r\n" # PHP_EOL by default; you can also use "\n"

Your IDE Integration

PHPStorm

EasyCodingStandard can be used as an External Tool

Go to Preferences > Tools > External Tools and click + to add a new tool.

• Name: ecs (Can be any value)
• Description: easyCodingStandard (Can be any value)
• Program: $ProjectFileDir$/vendor/bin/ecs (Path to ecs executable; On Windows path separators must be a \)
• Parameters: check $FilePathRelativeToProjectRoot$ (append --fix to auto-fix)
• Working directory: $ProjectFileDir$

Press Cmd/Ctrl + Shift + A (Find Action), search for ecs, and then hit Enter. It will run ecs for the current file.

To run ecs on a directory, right click on a folder in the project browser go to external tools and select ecs.

You can also create a keyboard shortcut in Preferences > Keymap to run ecs.

Visual Studio Code

EasyCodingStandard for Visual Studio Code extension adds support for running EasyCodingStandard inside the editor.

Tool Integration

Tool	Extension	Description
GrumPHP	nlubisch/grumphp-easycodingstandard	Provides a new task for GrumPHP which runs ECS

Contributing

Send issue or pull-request to main repository.