Glossary

ECS

In the context of PHP development, ECS means Easy Coding Standard here. It records team rules in version-controlled configuration so formatting and mechanical fixes do not become a recurring subject of code review.

Short definition

One entry point for consistent PHP style.

ECS brings together PHP_CodeSniffer and PHP-CS-Fixer rules and can run them in parallel over selected paths. Configuration in ecs.php defines source directories, rule sets, individual checkers, exceptions, and optionally a report format for CI.

The tool mainly addresses syntax and mechanically detectable code changes: whitespace, imports, parts of PHPDoc, array syntax, and other conventions. A clean ECS run alone does not prove correct behaviour, security, performance, or sound architecture; automatic rules therefore leave code review to focus on a change’s meaning and risks.

The problem it solves

Fewer manual formatting comments and more time to consider what a change means

A team can delegate unambiguous checks that would otherwise recur in every pull request to automation.

the same PHP file style in a developer editor and on the CI runner
automatically removing unused imports and fixing selected formatting
introducing a standard gradually into a legacy project in safe steps
a fast check before commit and a mandatory check before merge
a versioned, traceable agreement on applicable paths and rules

Practical example

Small configuration and a reviewable automatic fix

An online-store project configures ECS only for its own source and test code. On an ordinary run, the tool reports an unused import or array syntax that does not match the chosen standard. After running --fix, the developer reviews the diff and includes only an understandable change in the commit.

The example uses the current ECSConfig::configure() PHP configuration. Specific sets should follow team rules; enabling every available rule without review is not the goal.

PHP

// ecs.php
use Symplify\EasyCodingStandard\Config\ECSConfig;

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

// Před: use App\Unused\LegacyClient;
// Po běhu vendor/bin/ecs --fix zůstane jen používaný import.

How it works

From configuration to a check or controlled fix

ECS should not change source code invisibly. A normal workflow first shows the findings and a diff, then the developer deliberately reviews the fix.

Paths ecs.php selects directories such as src and tests; generated, cache, or migration files may be omitted with good reason.
Rules and sets The project activates a small group of specific checkers or a prepared standard such as PSR-12.
Check vendor/bin/ecs loads the configuration and reports violations or proposed changes for a specific file.
Fix vendor/bin/ecs --fix applies supported changes; the diff is always reviewed like any other edit.
CI gate CI runs the non-fixing check and fails clearly when a commit does not follow the agreed standard.

Main components

Configuration defines both scope and degree of intervention

Simple configuration is easier to maintain and reduces the risk of two fixers repeatedly overriding one another.

ECSConfig and paths

The configuration returns ECSConfig and explicitly lists source paths. This prevents accidental checking of vendor, cache, or files whose formatting the project does not own.

Prepared sets and checkers

Prepared sets group related rules. Individual checkers offer finer control when the team needs a specific exception or gradual rollout.

Check and --fix

Checking should be the safe default. The --fix option changes the working tree; it is appropriate locally or in a dedicated automated step, not as an invisible post-merge change.

Parallel execution and reports

ECS can split work across processes and create a machine-readable report. Speed matters only when the run remains stable and understandable.

Exceptions

withSkip should be narrow and justified, for example for a generated migration. A broad exception for an entire module merely hides an unresolved rule decision.

Benefits and limitations

Consistent style is not a measure of overall quality

Benefits

a repeatable standard independent of a particular editor configuration
fewer mechanical comments in code review
fast fixes for unambiguous deviations before a change is submitted
shared configuration for PHPCS and PHP-CS-Fixer rules in one tool

Limitations and common mistakes

automatically fixed code without reviewing the diff
too many sets and local exceptions instead of a clear standard
multiple fixers running together and switching formatting back and forth
confusing clean style with sound architecture, testing, or security

Pragmatic use

Start with a small rule set and expand only where it helps the team.

A new project can start with a few prepared rules and explicit paths. Legacy code is usually safer to migrate in stages: first low-risk rules, then one separate formatting commit, and finally checks on new changes. Mixing refactoring with mass formatting in one pull request makes review harder.

There is no need to deploy ECS alongside another fixer merely because it exists. The team should choose one clear formatting workflow, document it in the project, and preserve the ability to verify exactly what an automatic change did.

What to consider

Automation should be predictable and proportionate

A rule should have an owner, a clear benefit, and apply to code the team actually maintains.

keep ecs.php with the source code and run it with the same command locally and in CI
select only paths whose formatting the project owns
separate a large automated formatting commit from a business change
review the diff after every --fix run
configure CI to check, not silently edit a shared branch
review exceptions and unnecessary rules instead of layering them indefinitely

Common questions

Easy Coding Standard in practice

Is ECS the same as PHP_CodeSniffer?

No. ECS is a separate tool that runs PHP_CodeSniffer and PHP-CS-Fixer rules from one configuration. PHPCS has its own sniffs, rulesets, and PHPCBF tool.

Does ECS replace PHPStan?

No. ECS handles style and automatic formatting changes. PHPStan focuses on static analysis of types, calls, and contracts. A clean result from one tool does not imply success in the other.

Is using --fix in CI safe?

For an ordinary pull-request check, it is safer for CI to fail and for the fix to be applied in a controlled commit. An automatic fixer can change files, so its diff must be reviewable and have a clear owner.

Does ECS make sense for a small project?

Yes, if the team repeatedly discusses style or wants a consistent local and CI command. For a one-off script, however, extensive configuration may cost more time than it saves.

How I work with quality checks

Mechanical rules belong in a tool; technical decisions belong in review.

I use automated style as fast feedback alongside tests and static analysis. This lets review focus on the risks and meaning of the change.

View my testing and quality experience Discuss your project without obligation

Official Easy Coding Standard README