Setting up WordPress’s PHP coding standards for your theme
Tags: wordpress, php, codequality
Published: 2020-06-05 12:28:06

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](https://github.com/prtksxna/zuari/) 👀). Here is a quick guide on setting up the [WordPress PHP Coding Standards](https://github.com/WordPress/WordPress-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](https://prtksxna.com/2018/10/03/docker-compose-for-local-wordpress-development/). We start by running `composer init`. This sets up the `composer.json` file and adds it to `.gitignore`. Next to get the [phpcs](https://github.com/squizlabs/PHP_CodeSniffer) and the [WordPress coding standards](https://github.com/WordPress/WordPress-Coding-Standards), we run:

```bash
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](https://github.com/DealerDirect/phpcodesniffer-composer-installer#calling-the-plugin-directly). 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:

```json
"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](https://github.com/WordPress/WordPress-Coding-Standards/blob/develop/phpcs.xml.dist.sample) that the WordPress Coding Standards provides:

```xml
<?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](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Advanced-Usage#ignoring-parts-of-a-file) 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](https://atom.io/packages/linter-phpcs) 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](https://unsplash.com/@otenteko) on [Unsplash](https://unsplash.com/photos/feXpdV001o4))