DOCSEARCHbyAlgolia
Submit Docs

Easy Coding Standard (ECS) Documentation

repository·main·Indexed 23 days ago

https://github.com/ecsphp/ecs

Easy Coding Standard (ECS) is a tool that combines PHP_CodeSniffer and PHP-CS-Fixer into a single utility for enforcing coding standards in PHP projects. It features a fluent API via ecs.php for configuration, prepared rule sets, gradual adoption levels, and .editorconfig support. The CLI provides commands to check and fix code, list active checkers, and export results in formats such as JSON, JUnit, checkstyle, and GitLab.

Tokens
2.7K
Snippets
10
Records
19
Agent score
81%

What's inside Easy Coding Standard (ECS)

  1. Use Prepared Sets

    main

    Prepared sets bundle curated rules to save time. You can enable the entire common set or specific topics using withPreparedSets().

    Available topics:

    • arrays: array syntax, spacing, trailing commas, indentation
    • spaces: whitespace, operator/type spacing, blank lines
    • namespaces: imports ordering, unused/needless-alias imports
    • docblocks: phpdoc tags, types, alignment, cleanup
    • controlStructures: control flow, casing, operators, class structure
    • comments: comment style, spacing, empty-comment cleanup
    • casing: native function/type, magic method, literal casing
    • cleanup: dead statements, useless returns/casts, unused closure imports

    To enable everything at once, use ->withPreparedSets(common: true).

    use Symplify\EasyCodingStandard\Config\ECSConfig;

return ECSConfig::configure()
    ->withPaths([__DIR__ . '/src', __DIR__ . '/tests'])
    ->withPreparedSets(
        arrays: true,
        spaces: true,
        namespaces: true,
        docblocks: true,
        controlStructures: true,
        comments: true,
        casing: true,
        cleanup: true,
    );

  2. Adopt coding standards gradually with Levels

    main

    To avoid massive diffs, you can adopt standards step-by-step. Use with*Level(N) methods (e.g., withSpacesLevel, withArrayLevel) to enable the first N+1 rules from a curated list, ordered from safest to most invasive. Increase the level as you clean your codebase.

    use Symplify\EasyCodingStandard\Config\ECSConfig;

return ECSConfig::configure()
    ->withPaths([__DIR__ . '/src', __DIR__ . '/tests'])
    ->withSpacesLevel(0)
    ->withArrayLevel(0)
    ->withControlStructuresLevel(0)
    ->withDocblockLevel(0);

  4. Configure ECS via ecs.php

    main

    ECS is configured using a PHP file (ecs.php) via the ECSConfig::configure() fluent API. You can define paths, individual rules, configured rules, and prepared sets.

    use PhpCsFixerixer\ArrayNotation\ArraySyntaxFixer;
use PhpCsFixer\Fixer\ListNotation\ListSyntaxFixer;
use Symplify\EasyCodingStandard\Config\ECSConfig;

return ECSConfig::configure()
    ->withPaths([__DIR__ . '/src', __DIR__ . '/tests'])

    // start slow with sole rules
    ->withRules([
        ListSyntaxFixer::class,
    ])
    ->withConfiguredRule(
        ArraySyntaxFixer::class,
        ['syntax' => 'long']
    )

    // apply full set
    ->withPreparedSets(psr12: true);

  5. Skip files or specific rules

    main

    Use withSkip() to exclude specific rules, specific rules in certain paths, or entire directories (using absolute paths or glob masks).

    use Symplify\EasyCodingStandard\Config\ECSConfig;

return ECSConfig::configure()
    ->withSkip([
        // skip single rule
        ArraySyntaxFixer::class,

        // skip single rule in specific paths
        ArraySyntaxFixer::class => [
            __DIR__ . '/src/ValueObject/',
        ],

        // skip directory by absolute or * mask
        __DIR__ . '/src/Migrations',

        // skip directories by mask
        __DIR__ . '/src/*/Legacy',
    ]);

  6. Use .editorconfig with ECS

    main

    By calling ->withEditorConfig() in ecs.php, ECS will automatically discover the .editorconfig file in your project root. It respects settings for:

    • indent_style
    • end_of_line
    • max_line_length
    • trim_trailing_whitespace
    • insert_final_newline
    • quote_type (only single and auto are supported)

    These settings take precedence over similar rules in sets like PSR12 to prevent conflicts.

    use Symplify\EasyCodingStandard\Config\ECSConfig;

return ECSConfig::configure()
    ->withPaths([__DIR__ . '/src', __DIR__ . '/tests'])
    ->withEditorConfig();

  7. Use PHP-CS-Fixer sets

    main

    You can include rule sets directly from PHP-CS-Fixer using the withPhpCsFixerSets() method.

    use Symplify\EasyCodingStandard\Config\ECSConfig;

return ECSConfig::configure()
    ->withPaths([__DIR__ . '/src', __DIR__ . '/tests'])
    ->withPhpCsFixerSets(perCS20: true, doctrineAnnotation: true);

  8. Include root files in configuration

    main

    By default, ECS scans directories provided in withPaths(). To include files in your project root (like ecs.php or rector.php), use the withRootFiles() method.

    use Symplify\EasyCodingStandard\Config\ECSConfig;

return ECSConfig::configure()
    ->withPaths([__DIR__ . '/src', __DIR__ . '/tests'])
    ->withRootFiles();

  9. Configure output formats for CI/CD

    main

    You can specify an output format using the --output-format flag. Supported formats include:

    • console: Human-oriented (default).
    • json: Custom JSON blob for tooling.
    • junit: For CI environments.
    • checkstyle: For GitHub Action Reports.
    • gitlab: For GitLab code quality or Code Climate.
    vendor/bin/ecs --output-format=checkstyle

  10. Get checker list in JSON format

    main

    To use the list of checkers in another tool or for automated verification, run list-checkers with the --output-format=json flag. The resulting JSON object contains the following keys:

    • sniffs: An array of class names for PHP_CodeSniffer sniffs.
    • fixers: An array of class names for PHP-CS-Fixer fixers.
    • skipped-checkers: An array of class names that are currently being skipped.

  11. Use the ECS CLI

    main

    Run ECS using the vendor binary. On the first run, ECS will automatically create an ecs.php configuration file.

    • Run checks: vendor/bin/ecs
    • Check specific paths: vendor/bin/ecs src tests
    • Fix code automatically: Add the --fix flag to apply suggested changes.
    • Clear cache: vendor/bin/ecs --clear-cache
    • List active checkers: vendor/bin/ecs list-checkers
    vendor/bin/ecs --fix