Setting up WordPress’s PHP coding standards for your theme

Setting up coding standards for your project is always a good idea. While it is ideal to start with one from the beginning, sometimes you have to do it after you’ve already written quite a bit of code (looks at Zuari 👀). Here is a quick guide on setting up the WordPress PHP Coding Standards for your theme or plugin:

For the purpose of this guide you’d need PHP and Composer installed locally, even if you are using docker for local development. We start by running composer init. This sets up the composer.json file and adds it to .gitignore. Next to get the phpcs and the WordPress coding standards, we run:

composer require squizlabs/php_codesniffer --dev
composer require wp-coding-standards/wpcs --dev
composer require dealerdirect/phpcodesniffer-composer-installer --dev
composer require phpcompatibility/php-compatibility --dev

Now, to make sure that things are set up correctly on a fresh install we’ll create scripts that’ll run automatically post install. You can read more about this in the PHP_CodeSniffer standards composer installer plugin documentation. We’ll also add a script to actually run phpcs from inside of ./vendor/bin, this will serve as a shorthand when we need it later. So in composer.json we’ll add a new key called scripts:

"scripts": {
  "lint": "phpcs",
  "install-codestandards": ["Dealerdirect\\Composer\\Plugin\\Installers\\PHPCodeSniffer\\Plugin::run"],
  "post-install-cmd": [
    "@install-codestandards"
  ]
}

If we try to run composer run-script lint now it will start showing us a ton of linting errors. These might be a bit more than we actually need to resolve though, and that is because we haven’t yet defined which coding standard we’ll be following. To do this we’ll create a phpcs.xml.dist file and copy over the contents from the sample config file that the WordPress Coding Standards provides:

<?xml version="1.0"?>
<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="Your Project" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/squizlabs/PHP_CodeSniffer/master/phpcs.xsd">
    <description>A custom set of rules to check for a WPized WordPress project</description>
    <exclude-pattern>/docroot/wp-admin/*</exclude-pattern>
    <exclude-pattern>/docroot/wp-includes/*</exclude-pattern>
    <exclude-pattern>/docroot/wp-*.php</exclude-pattern>
    <exclude-pattern>/docroot/index.php</exclude-pattern>
    <exclude-pattern>/docroot/xmlrpc.php</exclude-pattern>
    <exclude-pattern>/docroot/wp-content/plugins/*</exclude-pattern>
    <exclude-pattern>/vendor/*</exclude-pattern>
    <exclude-pattern>/node_modules/*</exclude-pattern>
    <exclude-pattern>*.min.js</exclude-pattern>

    <rule ref="WordPress-Docs"/>
    <rule ref="Generic.CodeAnalysis.UnusedFunctionParameter"/>
    <rule ref="Generic.Commenting.Todo"/>

    <config name="minimum_supported_wp_version" value="4.9"/>
    <rule ref="WordPress.WP.I18n">
        <properties>
        <property name="text_domain" type="array">
        <element value="my-textdomain"/>
        </property>
        </properties>
    </rule>

    <rule ref="WordPress.NamingConventions.PrefixAllGlobals">
        <properties>
        <property name="prefixes" type="array">
        <element value="my_prefix"/>
        </property>
        </properties>
    </rule>

</ruleset>

Now we just need to make some adjustments to this file based on our theme and preferences. Look at the exclude-patterns, is there anything else that we should be excluding? Next, let’s make sure that the minimum_supported_wp_version is set correctly. Finally, we’ll fix the prefixes and text_domain to use your theme name. Make sure you use “-” for the text_domain and “_” for the prefixes.

And that’s it 🎉 You should be ready to go! Running composer lint will show you all the places where you aren’t following WordPress’s coding standards. Take some time to clean up all the errors and warnings and ignore the ones that you think aren’t appropriate. Marvel at your clean and beautiful code 😍

The only thing left to do is to make sure that things stay nice and clean over time. Atom has a package to see linting issues in the editor itself, and you can find and set one up for the editor of your choice. I would like to set this up on CI too, making sure something is looking at these errors even when I am not.

(Photo by Anas Alshanti on Unsplash)