PHP CS Fixer: automatic PHP coding standards fixes, and where it stops

The problem PHP CS Fixer solves for teams that already lint

A linter tells you that a file violates a coding standard. Someone still has to open the file and change it. On a large project that work is repetitive, and it is the kind of work that gets deferred until a standards discussion turns into a week of manual edits. PHP CS Fixer takes the other position: it detects the problem and applies the change itself. The README states the tool "not only detects them, but also fixes them for you".

The audience is PHP teams that have already decided on a style and want the codebase to keep matching it without a human in the loop. That includes libraries that want to accept contributions in a consistent format, and applications that inherit a mixed history of styles. The tool ships built-in rule sets for PHP-FIG's PER Coding Style (@PER-CS), the Symfony community standard (@Symfony), and its own opinionated set (@PhpCsFixer). It also ships @auto and @auto:risky, described in the README as aiming "to provide good base rules".

That framing matters for adoption. If your team has no agreed style, PHP CS Fixer will not create one for you. It will apply whichever set you name, and the diff will be large the first time.

How the fixer works: rules, rule sets and the config file

The unit of behaviour is a rule. A rule set is a named collection of rules. @PER-CS, @Symfony and @PhpCsFixer are rule sets; the repository also documents a built-in rules index and a configuration file format. When you run the tool, it reads your configuration, resolves the rule set into individual rules, and applies each rule to the files it was given.

The README points at three separate documents for this: the list of built-in rules, the list of rule sets, and the configuration file. The configuration file is where a team departs from a stock set, either by adding rules the set does not include or by overriding the ones it does. The repository's own top-level entries include .php-cs-fixer.dist.php, .php-cs-fixer.php-highest.php and .php-cs-fixer.php-lowest.php, which is the project applying that same configuration mechanism to itself at different PHP version targets.

Beyond formatting, the tool has rule sets aimed at code migration rather than style: @autoPHPMigration and @autoPHPMigration:risky for newer PHP, and @autoPHPUnitMigration:risky for newer PHPUnit. That is a different job from indentation, and it is worth treating as a different job when you decide what to enable.

Installing PHP CS Fixer with Composer and running a first check

The README calls Composer the recommended installation path. The package is friendsofphp/php-cs-fixer, installed as a dev dependency. The README also gives an alternative package, php-cs-fixer/shim, for cases where the normal install runs into dependency conflicts.

composer require --dev friendsofphp/php-cs-fixer

After that, the README shows an init command that writes a base configuration for the project:

./vendor/bin/php-cs-fixer init

With a configuration in place you can either rewrite files or only report what would change. The README gives both commands, and the distinction is the one that matters on a first run:

./vendor/bin/php-cs-fixer fix
./vendor/bin/php-cs-fixer check

Run check first. It tells you whether the project needs changes without touching the working tree, which is how you find out how big the initial diff will be. The README notes other installation methods, including Docker and installation behind CI, in a separate installation document.

PHP version support and the --allow-unsupported-php-version escape hatch

The README lists PHP 7.4 through PHP 8.5 as supported. It then adds a caveat that is easy to skim past: each new PHP version requires a large effort to support the new syntax, so the latest PHP release may not be supported yet. The project asks for contributions or PR review in that case.

There is an escape hatch. The README documents the option --allow-unsupported-php-version=yes, described as running the tool on yet unsupported versions "at your own risk". That wording is the project's, and it is accurate about the trade-off: you get the tool running, and you accept that the project has not committed to parsing that syntax correctly.

If you are on a PHP version outside the documented range, this is the decision point. Running with the flag on a codebase that uses new syntax is not the same as running on a supported version, and a fixer that misreads syntax can rewrite code you did not intend to change. The safe sequence is to try check with the flag, inspect the diff, and only then consider fix.

Where PHP CS Fixer is the wrong tool: static analysis and type errors

PHP CS Fixer changes style and, through the migration rule sets, some syntax. It does not do what a static analyser does. A type error, an unreachable branch, a call to a method that does not exist on the class: none of these are coding standards issues, and the tool has no rule category for them. Teams sometimes reach for a fixer because it is already wired into CI and looks like a quality gate. It is a formatting gate.

The second limitation is scope of change. Because fix rewrites files in place, a rule set that is broader than your current style produces a large diff. The README's own example sets, @auto and @auto:risky, are described as aiming to provide good base rules, which is a starting point rather than a guarantee that every rule suits your codebase. The risky variants exist precisely because some rules change behaviour in ways that need review.

The third is the unsupported-version boundary described above. If your project tracks a PHP release the tool has not caught up with, you are outside the supported range and relying on an option the README labels at your own risk.

PHP CS Fixer compared with PHP_CodeSniffer's phpcbf

The closest comparison is PHP_CodeSniffer and its companion fixer, phpcbf. Both read a style definition and both can rewrite files. The difference is where the definition lives. PHP_CodeSniffer defines standards as sniffs, and its ecosystem is built around published standards such as PSR-12 and framework-specific rule sets that you install as separate packages. PHP CS Fixer ships its rule sets inside the tool, so @PER-CS, @Symfony and @PhpCsFixer are available after one Composer require, and customisation happens in the fixer's own configuration file rather than by assembling sniff packages.

That makes PHP CS Fixer the shorter path when one of the built-in sets matches your intended style, and the more awkward path when your style is defined as a set of sniffs you already maintain. The README does document creating custom rules for styles that are not built in, so the door is open, but it is a different kind of work from installing an existing standard.

A second practical difference is the migration rule sets. @autoPHPMigration and @autoPHPUnitMigration:risky target version upgrades rather than formatting. That is a use case a pure coding-standards linter does not cover.

FAQ

Answers to the questions people actually search for about PHP CS Fixer, limited to what the README and repository files document.

Editorial conclusion

Adopt PHP CS Fixer if you want style enforced by rewriting files rather than by reporting them, and if your team can agree on one rule set such as @PER-CS or @Symfony. Do not adopt it as a replacement for static analysis: it changes formatting and some syntax, not type correctness. Before rolling it out, run check rather than fix on a clean branch, read the resulting diff, and confirm the PHP version you target is inside the documented range of PHP 7.4 to PHP 8.5.

Frequently asked questions

Official sources

1. License: MIT
2. PHP-CS-Fixer/PHP-CS-Fixer on GitHub
3. Project website
4. README
5. Releases