How to Install, Configure, and Automate PHP CS Fixer for Consistent Code Style

Introduction

Maintaining a consistent code style improves readability, reduces cognitive load, and ensures that every team member follows the same standards. Manual formatting is time‑consuming and error‑prone, so a dedicated tool that works across environments and CI pipelines is preferred.

Installing PHP CS Fixer

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

Creating a Configuration File

After installation, create a .php-cs-fixer.dist.php file at the project root to define the coding standards, target directories, and any custom rules.

<?php
declare(strict_types=1);

use PhpCsFixer\Config;
use PhpCsFixer\Finder;

return (new Config())
    ->setRules([
        '@PSR12' => true,
    ])
    ->setFinder(
        (new Finder())
            ->in(__DIR__)
    );

You can limit the scan to specific folders by adjusting the setFinder call, for example to only src and tests directories.

<?php
declare(strict_types=1);

use PhpCsFixer\Config;
use PhpCsFixer\Finder;

return (new Config())
    ->setRules([
        '@PSR12' => true,
    ])
    ->setFinder(
        (new Finder())
            ->in([__DIR__ . '/src', __DIR__ . '/tests'])
    );

For a full list of rules, consult the official documentation on GitHub.

Running PHP CS Fixer

Two main commands are used: ./vendor/bin/php-cs-fixer check – checks the code against the configured rules and lists violations. ./vendor/bin/php-cs-fixer fix – automatically fixes violations.

Example output for check shows the number of files examined, violations found, and execution time.

./vendor/bin/php-cs-fixer check
... (output showing 2 of 20 files can be fixed) ...

Running fix applies the changes and reports the fixed files.

./vendor/bin/php-cs-fixer fix
... (output showing 2 files fixed) ...

Running in Parallel Mode

Parallel execution speeds up analysis for large codebases. Enable it by adding setParallelConfig to the configuration.

<?php
declare(strict_types=1);

use PhpCsFixer\Config;
use PhpCsFixer\Finder;
use PhpCsFixer\Runner\Parallel\ParallelConfigFactory;

return (new Config())
    ->setRules(['@PSR12' => true])
    ->setFinder((new Finder())->in(__DIR__))
    ->setParallelConfig(ParallelConfigFactory::detect());

When executed, the tool reports the number of cores used and the parallel processing details.

Automating with GitHub Actions

A typical workflow runs the check command on every pull request. If violations are found, the job fails, prompting developers to fix issues locally.

# .github/workflows/ci-code-style.yml
name: Code Style

on:
  pull_request:

jobs:
  php-cs-fixer:
    runs-on: ubuntu-latest
    steps:
      - name: Update apt
        run: sudo apt-get update --fix-missing
      - name: Checkout code
        uses: actions/checkout@v2
      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: 8.4
          coverage: none
      - name: Install dependencies
        run: |
          composer install
      - name: Run PHP CS Fixer
        run: ./vendor/bin/php-cs-fixer check

While you can run fix in the workflow, it is generally recommended to run check only and let developers apply fixes locally to avoid unintended changes.

Conclusion

By installing PHP CS Fixer, configuring a ruleset, using it locally or in parallel mode, and automating checks with GitHub Actions, you can enforce a uniform coding style across PHP projects and improve overall code quality.