💩 Your WordPress PHP code stinks! Here’s why.

In software development, as in all forms of engineering, we strive to produce results that satisfy a multitude of constraints, some more obvious than others. High code quality should be in your list of constraints when you write WordPress PHP code. And there are tools out there that can help you!

First, some theory

In a fantasy world where unicorns poop chocolate fudge and everything is awesome, it all goes down somewhat like this: You talk with the client or end user, and you gather up a list of things they want. You collect and number these in a requirements document, braking them up into Functional requirements, Non-functional requirements, and other Design constraints. Then, you design a solution, write your tests, and implement your code. Once all of the requirements in the document are met, you are done, and you get paid. Easy! Deviate from this simple methodology at your own peril. (Oh, and you also then need to maintain, fix and improve the code you’ve written.)

As a software engineer, you should know that in addition to what the client asks for, there are always implicit requirements. For example, your code must be readable and maintainable, and it must be reliable (read: not too buggy). All of these are aspects of code quality. A client or end user will never ask you for these, but you should have them in your list of non-functional requirements.

Professional developers write simple, clear code where a novice would write complex, intricate code to solve that same problem. Sure, a lot of this is just a matter of practice and experience.

Dev tools can help you with code quality whether you’re novice or pro. They help you discover issues that you don’t know about, and they help you discover issues that you do know about, faster!

If you are developing themes or plugins, here’s two tools that you definitely want to use as a professional WordPress developer:

Improve WordPress PHP code smell with CodeSniffer

There are some styling guidelines that all WordPress developers should follow. Especially if you are aspiring to upload your code to wordpress.org, or to the Envato Market (ThemeForest or CodeCanyon), then you definitely want to follow these guidelines. Generally, these get encoded into your muscle memory pretty quickly, but it’s always a great idea to have a tool like PHP CodeSniffer that double-checks your code style.

On my Ubuntu machine, I was able to install PHP CodeSniffer easily with:

sudo apt install php-codesniffer

Then, it’s just a matter of loading the WordPress-specific set of rules. Go to your home directory and clone the project:

git clone https://github.com/WordPress/WordPress-Coding-Standards ~/wpcs

And tell CodeSniffer the location of these rules:

sudo phpcs --config-set installed_paths ~/wpcs

Check that the new rules are added into CodeSniffer with:

phpcs -i

Congratulations! You can now check your plugin for code style with a command such as:

phpcs --standard=Wordpress-Core /path/to/source/code/root/dir

If, like me, you’re using grunt for your build process, then there’s a nifty Grung plugin, grunt-phpcs. Just make sure to specify WordPress-core as the rule set. Here’s a grunt target that you might use:

phpcs: {
    plugin: {
        src: ['src/**/*.php']
    },
    options: {
        bin: '/usr/bin/phpcs',
        standard: 'WordPress-core'
    }
}

Run it against your code and you will get a number of improvement suggestions. Some of these can be applied automatically with PHPCBF (the PHP Code Beautifier and Fixer), or you can go through the list manually and apply each suggestion as you see fit. Many of the suggestions will be related to code indentation, but you will also see a large number of other suggestions that are more critical.

Improve WordPress PHP code correctness with phan

PHP is a very lenient language. It will let you get away with murder. This is something that novice programmers often enjoy. For professionals it’s a nightmare, as it makes spotting errors harder. PHP has thus gained somewhat of a notoriety for being a bad language, and is the butt of some clever jokes.

This isn’t something to worry about. It has happened to many respectable languages, including JavaScript. So nowadays we have use strict, which lets us only use The Good Parts of the language. You can do something similar with PHP.

My point is that static code analysis is not the hero you want, but it’s definitely the hero you deserve. Enter phan:

First, install it. It’s straightforward to install phan with composer:

composer require phan/phan

Now phan lives in your project’s vendor/ dir.

Next, create a configuration under your project dir, in .phan/config.php. This will tell phan what settings you want to run it with. Start with the example given here, and set your source code directories.

You will also want to point to some third-party code, including the directory of your WordPress installation, since your code will invariably use WordPress functions and types.

You can also use this config file to exclude some rules, so that phan does not check for them. Here’s the complete list of phan plugins.

When all is set, you can call phan on your code with:

vendor/bin/phan

I don’t care how pro you are, you will definitely get a list of suggestions on how to improve your code.

Conclusion

Using phpcs and phan together, you will avoid a large number of errors that would otherwise likely go undetected. These include errors with translator comments over strings, phpDoc formatting errors, variable type errors, errors related to sentinel values such as null, and array indexing errors.

Always use these two tools together with phpunit when you write code. You will write more readable, maintainable, correct and robust code that you can feel confident about.