Jan Mikoláš
Glossary
PHP_CodeSniffer
PHP_CodeSniffer standardises rules of code style that can be checked automatically. It saves a team from repeated comments in code review without replacing tests or design discussions.
Short definition
Checking an agreed code style, not proving an application correct.
PHP_CodeSniffer is commonly abbreviated to PHPCS. As it processes a file, it divides it into PHP tokens, and each active sniff—an individual checking rule—examines a specific aspect of the code. It can therefore find violations of PSR-12 as well as rules agreed by a particular team.
A second command, PHPCBF, or PHP Code Beautifier and Fixer, fixes only findings for which the given sniff provides a safe automatic correction. A clean PHPCS result therefore does not mean that the application has correct types, architecture, or business logic.
Use cases
When checking standards is useful
It provides the most value where several people work on the code or the project lives long enough for inconsistent style to start slowing down reading and changes.
- standardising file formatting, indentation, spacing, and the order of selected parts of a PHP file
- checking team conventions for names, imports, comments, and prohibited constructs
- automatically fixing unambiguous changes with PHPCBF before a commit or in an editor
- quickly checking changed files in a pull request and in CI
- gradually introducing stable rules into an older PHP project
Practical example
A ruleset for application source code
An e-commerce administration interface can use PSR-12 as a shared foundation and adjust only a few specific rules. The configuration is stored in the repository, so the local editor and CI assess the same source code in the same way.
This ruleset checks the project root, omits generated data in var, and sets a readable line-length limit. The team should add a custom rule only when it has a clear, long-term reason to do so.
<?xml version="1.0"?>
<ruleset name="Projekt">
<rule ref="PSR12"/>
<file>.</file>
<exclude-pattern>*/var/*</exclude-pattern>
<rule ref="Generic.Files.LineLength">
<properties>
<property name="lineLimit" value="120"/>
</properties>
</rule>
</ruleset>How it works
From a ruleset to clear feedback
PHPCS does not compare a file with a single template character by character. It applies a set of rules that respond to specific tokens and constructs.
- File selection The command or ruleset defines directories, extensions, and any exceptions.
- Ruleset It loads PSR-12, another installed standard, or a custom combination of rules.
- Tokenization The source code is divided into PHP tokens such as classes, methods, brackets, and imports.
- Sniffs Individual sniffs evaluate relevant tokens and report an error or warning, including the identifier of the specific rule.
- Fix and gate PHPCBF fixes only fixable findings; PHPCS can then remain a required check before merging.
Main components
A standard, ruleset, sniff, and fixer are not the same thing
Precise terminology helps configure rules that are predictable for the team.
Coding standard
A set of conventions for writing code, such as PSR-12. Its purpose is to reduce the effort required to read code from different authors.
Sniff
One checking rule within a standard, for example for indentation, line length, or import order.
Ruleset
Project XML configuration that combines standards, excludes rules, changes their properties, and limits the paths being checked.
PHPCS
The checking command that reports rule violations, their line number, and the identifier of the specific sniff.
PHPCBF
A companion fixer for automatically correctable PHPCS findings. The resulting change should be reviewed in the diff.
Benefits and limitations
Support for focus, not a replacement for technical judgement
Benefits
- code assessed consistently in the IDE, before a commit, and in CI
- fewer repeated formatting comments during code review
- fast automatic fixes for unambiguous style deviations
- named and versioned rules instead of unwritten customs
Limitations and common mistakes
- flawless style does not prove correct architecture, security, or business rules
- too many local rules and exceptions can add more overhead than value
- not every PHPCBF fix is appropriate without reviewing the change in the diff
- suppressing findings without justification can easily undermine confidence in the rules
Sensible adoption
Rules should be stable, automatable, and understood by the whole team.
An established standard such as PSR-12 and a small number of rules reflecting the repository’s actual needs are usually enough as a foundation. If a project uses an existing company standard, consistent use and a clear explanation of exceptions matter more than collecting as many sniffs as possible.
PHPCS can run when a file is saved, in a Git hook, and in CI. It is practical to resolve automatically fixable findings before sending a change; unresolved or non-automatable problems should then have a clear message and appropriate severity.
What to consider
Automation should simplify the team’s work
The goal is not the longest configuration but removing mechanical decisions from day-to-day collaboration.
- a ruleset versioned with the source code
- a default standard with a minimum of justified changes
- excluding generated files and external code from checks
- PHPCBF for safely fixable deviations
- fast checks of changes in the IDE or pre-commit and a complete check in CI
- regular review of exceptions and custom sniffs
Common questions
PHP_CodeSniffer in practice
Is PHP_CodeSniffer a static analysis tool?
It checks source code without running it, but its primary purpose is coding standards. PHPStan analyses types, possible calls, and contracts; the two tools complement rather than replace each other.
Does PHPCBF replace code review?
No. It removes only some mechanical style deviations. Code review still addresses design, clarity of the change, security, and domain decisions.
Should a team use PHPCBF, ECS, and PHP-CS-Fixer together?
Only if there is a clear reason for the overlap and the tools’ rules do not overwrite one another’s changes. For a typical project, it is more practical to designate one automatic formatting tool and keep its configuration simple.
Is PSR-12 mandatory for every PHP project?
No. It is a widely used default standard, not a law. A project can use another or an extended standard for good reason, but the team should apply it consistently.
How I use quality checks in practice
Standards make sense alongside tests, analysis, and architectural rules.
I use PHP_CodeSniffer as one layer of continuous feedback. Mechanical rules keep the code style consistent so that review can focus on the risks of a change.