Setup PHP-CS-Fixer

28 Apr 2021

Hello! Today I would like to share PHP-CS-Fixer configuration for PHP project. PHP-CS-Fixer is used for automated code formatting based on specific rules, for example, PSR standards.

PHP-CS-Fixer would help to improve code quality. Following code quality standards would make project code base better for understanding and simplify development in general. It also would optimize code review process.

Install

PHP-CS-Fixer can be installed with composer:

composer require friendsofphp/php-cs-fixer

If needed, it also can be installed globally.

Configuration

Need to create .php_cs file in project root. For Symfony project I usually use such configuration:

<?php

declare(strict_types=1);

$finder = PhpCsFixer\Finder::create()
    ->exclude('Migrations')
    ->in(__DIR__ . '/src')
    ->in(__DIR__ . '/tests');

return PhpCsFixer\Config::create()
    ->setRiskyAllowed(true)
    ->setRules([
        '@Symfony' => true,
        '@PHP71Migration:risky' => true,
        'concat_space' => ['spacing' => 'one'],
        'psr0' => false,
        'array_syntax' => ['syntax' => 'short'],
        'class_definition' => ['multiLineExtendsEachSingleLine' => true],
        'no_useless_else' => true,
        'ordered_imports' => ['sort_algorithm' => 'alpha'],
        'phpdoc_add_missing_param_annotation' => ['only_untyped' => true],
        'no_short_echo_tag' => true,
        'list_syntax' => ['syntax' => 'short'],
        'linebreak_after_opening_tag' => true,
        'void_return' => false,
        'phpdoc_summary' => false,
        'multiline_whitespace_before_semicolons' => ['strategy' => 'new_line_for_chained_calls'],
        'visibility_required' => ['property', 'method', 'const'],
    ])
    ->setCacheFile(__DIR__ . '/.php_cs.cache')
    ->setFinder($finder);

Describe command can be used for getting information about specific rule:

vendor/bin/php-cs-fixer describe concat_space

Detailed description of rule and all parameters will be displayed in console.

Run

Automatic code formatting can be run with such command:

vendor/bin/php-cs-fixer fix --allow-risky=yes --using-cache=no --config .php_cs

It also can applied to specific file or directory:

vendor/bin/php-cs-fixer fix --allow-risky=yes --using-cache=no --config .php_cs src/Command/
vendor/bin/php-cs-fixer fix --allow-risky=yes --using-cache=no --config .php_cs src/Command/MyConsoleCommand.php

Parameter --allow-risky=yes is responsible for applying "risky" rules. For example, adding strict types can break existing code, then this rule is risky. Parameter --using-cache=no is responsible for disabling cache. It makes sense to disable cache if there are not so many files and PHP-CS-Fixer run doesn't take much time. Parameter --config .php_cs is responsible for specify rules configuration file.

Extra

I recommend running PHP-CS-Fixer continiously in CI/CD. There is github actions example:

steps:
  - name: PHP-CS-Fixer
    uses: docker://oskarstark/php-cs-fixer-ga
    with:
      args: --config=.php_cs.dist --diff --dry-run

I also recommend add shortcut to composer.json. Then PHP-CS-Fixer can be run with simple command: composer cs-fixer.

{
    ...
    "scripts": {
        ...
        "cs-fixer": [
            "vendor/bin/php-cs-fixer fix --allow-risky=yes --using-cache=no --config .php_cs"
        ],
        ...
    }
    ...
}

Configuration file is also available on gist.

That's all for today. Thank you for your attention!