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

README.md

The Easiest Way to Use Any Coding Standard

Build Status Downloads total Subscribe

Used by Shopsys, Nette, Sylius, php-ai/php-ml, LMC and Sunfox.

ECS-Run

Features

Are you already using another tool?

Install

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

Usage

1. Create Configuration and Setup Checkers

Create an easy-coding-standard.yml 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

ECS-Run

More Features

Use Prepared Checker Sets

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

You pick config in CLI with --config:

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

Too long? Try --level shortcut:

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

or include more of them in config:

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

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

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

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

Exclude Checkers

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

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

parameters:
    exclude_checkers:
        - 'PhpCsFixer\Fixer\PhpTag\BlankLineAfterOpeningTagFixer'

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 that you know from PHP_CodeSniffer:

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

        # 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.yml 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
     */
    public function find(array $source): IteratorAggregate
    {
        # $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.

FAQ

How to show all loaded checkers?

vendor/bin/ecs show

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

How to 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 to clear cache?

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

How about changing cache directory?

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

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

parameters:
    indentation: "tab" # "spaces" by default
    line_ending: "\r\n" # PHP_EOL by default

To use "\n" on the other hand:

parameters:
    line_ending: "\n"

Your IDE Integration

PHPStorm

EasyCodingStandard can be used as an External Tool

PHPStorm Configuration

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.

Contributing

Send issue or pull-request to main repository.