Why doesn’t PHP have more uniform, opinionated, styles? We see it with so many other languages…

  • Go: gofmt automatically formats Go source code. According to go.dev, 70% of Go packages in the wild are formatted with gofmt.
  • JavaScript: Prettier is an opinionated code formatted used by many packages.
  • Python: Black, the uncompromising Python code formatter.
  • C#: A decent formatter is built into Visual Studio, nothing additional required. Or you can go with a more opinionated option like CSharpier.
  • Java: There’s lots of options for Java. For instance, a popular option is Google’s standard formatter.

What options do PHP developers have?

In typical PHP fashion, we have a lot choices… This is a blessing and a curse working in such a mature language. I uncovered while researching static analysis tools that there are two dominate tools for styling php, neither very opinionated out of the box.

PHP_CodeSniffer & PHP-CS-Fixer

The main difference between these two is that PHP-CS-Fixer is fully automated. Once it’s configured any issues it finds it will always fix.

PHP_CodeSniffer is more likely to tell you what’s wrong and may not be able to fix issues. You can have it try to fix issues by running it’s alt command, phpcbf, but this only works half of the time.

I won’t get into specific details about how to install or run these tools, the documentation is great if you want to check that out. But I will briefly explain how these are configured to give more context.

PHP_CodeSniffer Configuration

PHP_CodeSniffer is the original style tool for PHP, it’s been around since 2009!

Configured with a phpcs.xml file or a phpcs.xml.dist file, this project is highly un-opinionated. The most standardized configs are the PSR styles included with the package, however many projects override these defaults and in general projects that use phpcs do not share a common style.

Given it’s age it’s not surprising that it uses XML for configuration. Back in 2009, everything was configured with XML. Checkout the config used by the PHP_CodeSniffer project itself as an example.

Checkout some configs of a few large projects

Configuring PHP-CS-Fixer

PHP-CS-Fixer is the new kid on the block. It was release in 2015 and is developed by Sensio Labs who also develops Symfony, one of the most popular PHP frameworks. It’s also fairly un-opinionated, and again, most projects write their own configs.

It’s configured with a PHP file, sometimes as .php_cs, or .php-cs-fixer.dist.php, or .php-cs-fixer.php. Checkout the config used by the PHP-CS-Fixer project itself as an example.

When I first looked at one of these configurations it looked confusing enough that I didn’t even try to use this tool. The setup also isn’t straightforward. However, it’s not as scary as it looks, and this tool does work very well once configured.

Checkout some configs of a few large projects

Introducing PHPStyle ✨

Confused yet? In my quest for quickly applying styles to my projects I instead discovered that there’s not a single right answer. PHP developers develop new standards for every project. Sometimes using the same tools, and sometimes giving up and not using any automated tools at all. 🙁

So I’ve created yet another project to make this journey easier for my own projects, and maybe yours too.

PHPStyle is easy to use, opinionated, and configured with a Neon/Yaml file (not PHP or XML). It uses PHP-CS-Fixer under the hood so as that project improves this one will as well.

How to use PHPStyle

  1. Require the package
    1
    
    composer require jspaetzel/phpstyle --dev
    
  2. Run the setup script:
1
./vendor/bin/phpstyle-setup

🗒 Note: This script is for convenience, you can alternatively do the same steps manually by installing php-cs-fixer and copying this .php-cs-fixer.dist.php file to your project root.

  1. Create/review the phpstyle.neon configuration file. Feel free to make changes to this file again at any time.
1
2
3
4
5
6
7
8
9
parameters:
    php: 7.4
    risky: false
    paths:
        - src
        - tests
    excludePaths:
        - src/path/you/want/to/skip
        - src/or/a/file-to-skip.php
  1. Run php-cs-fixer to fix your code
    1
    
    ./vendor/bin/php-cs-fixer fix
    

🗒 Note: php-cs-fixer is integrated with PHPStorm and other editors and so PHPStyle should work with them as well.

That’s it, your code is styled!