Formatting PHP Code with PHP CS Fixer

Introduction

Maintaining a consistent code style is a key aspect of software and web development. It improves code readability, reduces developers' cognitive load, and ensures everyone on the team sticks to the same standards.

But manually formatting code style is time-consuming, tedious, and error-prone. It's possible to format your code automatically using your integrated development environment (IDE) or text editor, but this approach has its limitations. Not all team members may use the same tools, and IDE configurations can vary widely. So it's usually better to use a dedicated code style tool that can be run consistently across different environments and in your continuous integration (CI) pipeline.

One of the tools you can use for formatting your PHP code is PHP CS Fixer. It's an incredibly popular tool and, at the time of writing, has over 214 million downloads on Packagist.

In this article, we'll look at how to install and configure PHP CS Fixer. We'll then explore how to run it locally and in parallel mode. Finally, I'll show you how to create a GitHub Actions workflow to automate code style checks on pull requests using PHP CS Fixer.

Installing PHP CS Fixer

To get started with PHP CS Fixer, you'll first need to install it via Composer. You can do this by running the following command in your project's root directory.

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

Create the Config File

After it finishes installing, you'll then need to create a configuration file for PHP CS Fixer. This file allows you to specify the coding standards you want to enforce, the directory you want to run the tool against, and any custom rules you may have.

To do this, you'll need to create a .php-cs-fixer.dist.php file in the root directory of your project.

Let's look at an example configuration file:

declare(strict_types=1);

use PhpCsFixer\Config;
use PhpCsFixer\Finder;

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

In the config file above, we are specifying that we want to use the PSR-12 coding standard and that we want to scan all files in the current directory (and child directories) for code style issues.

If you want to run the tool against specific directories, you can modify the setFinder method. For example, let's imagine we only want to run the tool against the src and tests directories. We can do this by updating the setFinder method as follows:

declare(strict_types=1);

use PhpCsFixer\Config;
use PhpCsFixer\Finder;

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

There's a ton of configuration options and rules available for PHP CS Fixer, and I won't dive into them all here. But I'd recommend checking out the documentation on GitHub so you can find any other rules you may wish to use: https://github.com/PHP-CS-Fixer/PHP-CS-Fixer/blob/master/doc/rules/index.rst.

Formatting Code with PHP CS Fixer

Now that we have PHP CS Fixer installed and configured, we can run it against our codebase.

Typically, there are two commands you'll want to use:

• ./vendor/bin/php-cs-fixer check - This command checks your code for any style issues based on the rules defined in your configuration file. It will output a list of files that do not comply with the specified coding standards.
• ./vendor/bin/php-cs-fixer fix - This command automatically fixes any code style issues found in your codebase based on the rules defined in your configuration file.

So if we wanted to run the check command to see if there are any code style issues in our project, we would run the following command:

vendor/bin/php-cs-fixer check

And this would generate output similar to the following:

❯ ./vendor/bin/php-cs-fixer check
PHP CS Fixer 3.89.1 Folding Bike by Fabien Potencier, Dariusz Ruminski and contributors.
PHP runtime: 8.4.2
Running analysis on 1 core sequentially.
You can enable parallel runner and speed up the analysis! Please see usage docs for more information.
Loaded config default from "/Users/ashallen/www/open-source/packages/email-utilities/.php-cs-fixer.dist.php".
Using cache file ".php-cs-fixer.cache".
 20/20 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%

   1) tests/Feature/Email/DomainIsNotTest.php
   2) src/Email.php

Found 2 of 20 files that can be fixed in 0.026 seconds, 20.00 MB memory used

Similarly, to automatically fix the issues found, we can run the following command:

vendor/bin/php-cs-fixer fix

Running this command would fix any of the code style issues found in our project and generate an output like so:

❯ ./vendor/bin/php-cs-fixer fix  
PHP CS Fixer 3.89.1 Folding Bike by Fabien Potencier, Dariusz Ruminski and contributors.
PHP runtime: 8.4.2
Running analysis on 1 core sequentially.
You can enable parallel runner and speed up the analysis! Please see usage docs for more information.
Loaded config default from "/Users/ashallen/www/open-source/packages/email-utilities/.php-cs-fixer.dist.php".
Using cache file ".php-cs-fixer.cache".
 20/20 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%

   1) tests/Feature/Email/DomainIsNotTest.php
   2) src/Email.php

Fixed 2 of 20 files in 0.029 seconds, 20.00 MB memory use

Running PHP CS Fixer in Parallel Mode

PHP CS Fixer allows running checks and fixes in parallel. This can significantly speed up the process, especially for larger codebases.

You can enable parallel mode by updating your configuration file to include the setParallelConfig method. Here's an example of how to do this:

declare(strict_types=1);

use PhpCsFixer\Config;
use PhpCsFixer\Finder;

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

In the example above, we're letting PHP CS Fixer automatically detect the optimal parallel configuration for our system. But you can manually specify these details if you wish.

Running ./vendor/bin/php-cs-fixer fix will then run the fixer in parallel mode. You should see output similar to the following:

❯ ./vendor/bin/php-cs-fixer fix  
PHP CS Fixer 3.89.1 Folding Bike by Fabien Potencier, Dariusz Ruminski and contributors.
PHP runtime: 8.4.2
Running analysis on 7 cores with 10 files per process.
Parallel runner is an experimental feature and may be unstable, use it at your own risk. Feedback highly appreciated!
Loaded config default from "/Users/ashallen/www/open-source/packages/email-utilities/.php-cs-fixer.dist.php".
Using cache file ".php-cs-fixer.cache".
 20/20 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%

   1) src/Email.php

Fixed 1 of 20 files in 0.210 seconds, 20.00 MB memory used

Running PHP CS Fixer using GitHub Actions

A great way to ensure that your code style remains consistent across your team is to automate the code style checks. Doing this helps catch any instances where you forget to run the code formatter locally before pushing your changes.

To automate this process, I like to use a GitHub Actions workflow that runs on every pull request. Since PHP CS Fixer returns a non-zero exit code (indicating failure) if any code style issues are found, we can rely on this to fail the workflow.

Let's look at a typical GitHub Actions workflow you may want to use:

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

In the example above, we can see that we're running the ./vendor/bin/php-cs-fixer check command as part of the workflow. If any code style issues are found, the command will return a non-zero exit code, causing the workflow to fail. If the command passes, it will return a zero exit code, and the workflow will succeed.

Should I Fix Issues Automatically in the Workflow?

You may want to run the fix command and automatically commit the changes to the pull request. However, I generally avoid this approach because it can introduce unexpected changes to the codebase without my knowledge. Instead, I prefer to run the check command and then fix any issues locally. This way, I have full control over the changes being made to the codebase.

This is only my personal opinion, though, and you may find that automatically fixing issues in the workflow works better for your team. If you do want to fix the issues in your workflow automatically, you might want to consider opening a pull request via your workflow with the updated code style changes instead of committing them directly to the branch. This way, you can review the changes before they are merged into the main codebase.

Conclusion

In this article, we explored how to set up and use PHP CS Fixer for maintaining code style in your PHP projects. We covered installation, configuration, running it locally and in parallel mode, and automating code style checks using GitHub Actions. By integrating PHP CS Fixer into your development workflow, you can ensure consistent code quality and adherence to coding standards across your projects.

If you enjoyed reading this post, you might be interested in checking out my 220+ page ebook "Battle Ready Laravel" which covers similar topics in more depth.

Or, you might want to check out my other 440+ page ebook "Consuming APIs in Laravel" which teaches you how to use Laravel to consume APIs from other services.

If you're interested in getting updated each time I publish a new post, feel free to sign up for my newsletter below.

Keep on building awesome stuff! 🚀