PHP-CS-Fixer — Automatic PHP Code Style Fixer

Introduction

PHP-CS-Fixer scans PHP source files and automatically rewrites them to comply with a chosen coding standard. It eliminates style debates in code review by programmatically enforcing rules from PSR-12, PER, Symfony conventions, or any custom configuration.

What PHP-CS-Fixer Does

• Fixes PHP files to conform to PSR-1, PSR-2, PSR-12, PER, and Symfony coding standards
• Supports over 200 individual fixers covering spacing, alignment, imports, phpdoc, and control structures
• Runs in dry-run mode to report violations without modifying files
• Integrates with CI/CD pipelines to block merges that violate style rules
• Allows project-level configuration via a .php-cs-fixer.dist.php file

Architecture Overview

PHP-CS-Fixer parses each PHP file into a token stream using PHP's built-in tokenizer, applies an ordered chain of fixers to that stream, then writes the corrected tokens back to disk. Fixers are composable and dependency-aware: the tool resolves ordering conflicts automatically so that one fixer's output does not break another's assumptions.

Self-Hosting & Configuration

• Install globally via Composer or per-project as a dev dependency
• Create a .php-cs-fixer.dist.php config file to define rule sets and finder paths
• Use preset rule sets like @PSR12, @Symfony, or @PER-CS as a base, then override individual rules
• Run php-cs-fixer fix --dry-run --diff in CI to fail builds on style violations without changing files
• Cache results with --cache to skip unchanged files on subsequent runs

Key Features

• Over 200 fixers covering nearly every aspect of PHP code formatting
• Risky fixers (those that change code behavior) are opt-in and clearly labeled
• Parallel execution support for faster processing of large codebases
• Built-in caching avoids re-processing unchanged files across runs
• Active development with regular releases tracking the latest PHP language features

Comparison with Similar Tools

• PHP_CodeSniffer (phpcs/phpcbf) — sniffs and fixes; PHP-CS-Fixer focuses exclusively on automated fixing with a larger fixer library
• Laravel Pint — opinionated wrapper around PHP-CS-Fixer with Laravel-specific defaults
• Rector — handles code upgrades and refactoring; PHP-CS-Fixer focuses on style rather than logic changes
• PHPStan/Psalm — static analysis tools that find bugs; PHP-CS-Fixer addresses formatting only
• Prettier PHP Plugin — Prettier ecosystem; PHP-CS-Fixer offers deeper PHP-specific rule coverage

FAQ

Q: Can I use PHP-CS-Fixer alongside PHPStan or Psalm? A: Yes. PHP-CS-Fixer handles formatting while PHPStan and Psalm handle static analysis. They complement each other in CI pipelines.

Q: Does it support PHP 8.x syntax? A: Yes. Fixers are updated regularly to handle PHP 8.0 through 8.4 features including attributes, enums, readonly properties, and intersection types.

Q: How do I share configuration across multiple projects? A: Create a shared Composer package containing your .php-cs-fixer.dist.php config and install it as a dev dependency in each project.

Q: Will it change the behavior of my code? A: Standard fixers only change formatting. Risky fixers that could alter behavior (e.g., renaming functions) must be explicitly enabled.

Sources

• https://github.com/PHP-CS-Fixer/PHP-CS-Fixer
• https://cs.symfony.com/