PHP-CS-Fixer for PHP: Complete Guide with Examples

1. What It Is and Why You Need It

PHP-CS-Fixer (PHP Coding Standards Fixer) is a powerful tool for automatically formatting PHP code according to specified coding standards. It analyzes source code, detects formatting rule violations (indentation, whitespace, line breaks, import ordering, short syntax usage, etc.) and fixes them automatically. This library is an essential asset in modern PHP projects, especially for team development.

Why do you need it? First, it enforces a consistent code style across your team. When multiple developers work on the same project, each may have their own formatting habits. PHP-CS-Fixer eliminates this issue by standardizing all code. Second, it saves time during code review: instead of debating indentation and spacing, developers can focus on logic and architecture. Third, automated formatting prevents "noise" changes in commits, where editing one line triggers formatting changes across an entire file.

PHP-CS-Fixer supports over 100 built-in rules and allows you to create custom ones. The tool integrates easily into CI/CD pipelines, version control systems (via pre-commit hooks), and IDEs. It's compatible with PSR-1, PSR-2, PSR-12, Symfony, Doctrine, and other popular coding standards.

2. Installation

PHP-CS-Fixer is installed via Composer, PHP's dependency manager. It's recommended to install it globally or as a dev dependency in your project.

# Global installation (recommended for use across any project)
composer global require friendsofphp/php-cs-fixer

# Install as a dev dependency in a specific project
composer require --dev friendsofphp/php-cs-fixer

# Verify installation
php-cs-fixer --version

After global installation, make sure the ~/.composer/vendor/bin directory (or %USERPROFILE%\AppData\Roaming\Composer\vendor\bin on Windows) is added to your PATH environment variable.

3. Quick Start — Minimal Working Example

Create a file called example.php with messy code:

<?php
$name = "John";
$age=25;
function greet($name){
echo "Hello, ".$name;
}
greet($name);

Now format it using PHP-CS-Fixer:

php-cs-fixer fix example.php --rules=@PSR12

After running the command, the file will look like this:

<?php

$name = 'John';
$age = 25;

function greet($name): void
{
    echo 'Hello, '.$name;
}

greet($name);

As you can see, PHP-CS-Fixer added spaces around the assignment operator, replaced double quotes with single quotes (when no interpolation is needed), added a : void return type, formatted the curly braces, and added blank lines for better readability.

4. Key Methods/Functions/Classes

4.1. PhpCsFixer\Config::create()

Signature: public static Config::create(): Config

What it does: Creates a new configuration instance for setting up formatting rules.

<?php
use PhpCsFixer\Config;

$config = Config::create()
    ->setRules([
        '@PSR12' => true,
        'array_syntax' => ['syntax' => 'short'],
    ])
    ->setFinder(
        PhpCsFixer\Finder::create()
            ->in(__DIR__ . '/src')
    );

4.2. PhpCsFixer\Finder::create()

Signature: public static Finder::create(): Finder

What it does: Creates an object to find PHP files that need formatting.

<?php
use PhpCsFixer\Finder;

$f