PHPCS, an open source “code sniffing tool”, is essential for any WordPress developer. Indeed, if you’re a WordPress VIP client, it’s a requirement, as code is only allowed into production if it sniffs clean for a specific ruleset.

Let me explain a little more, including how you should be using it.

PHPCS – PHP Code Sniffing

PHPCS can be downloaded from Github, and integrations for popular code editors are documented. What I’m not going to do here is go through these, particularly as I would only confidently be able to show you how to do this on Mac and a subset of just one code editor.

If you don’t add code editor integration, you can run PHPCS from the command line – I use the latter for the tidying option (more on this) and for a mass-check over of a plugin folder, for example. When it then comes to individual file changes, I rely on the my editor integration, which I have set to sniff on file save.

But getting PHPCS in place is only half the story. Now you need some rulesets and, particularly, for WordPress.

The WordPress Coding Standards

The WordPress Coding Standards can now be downloaded and added (again I’m not going to cover this process as their Github page has full documentation). This adds the following rulesets…

• WordPress – complete set with all of the sniffs in the project
• WordPress-Core – main ruleset for WordPress core coding standards
• WordPress-Docs – additional ruleset for WordPress inline documentation standards
• WordPress-Extra – extended ruleset for recommended best practices, not sufficiently covered in the WordPress core coding standards
  • includes WordPress-Core

So, as a WordPress developer, it would make most sense to use the WordPress ruleset for on-going sniffs, as that is a complete set of rules, covering of all the other rules as well.

Should you use the VIP rulesets?

The WordPress VIP team have their own sets of rules. Install these and you will now have two further rulesets…

• WordPress-VIP-Go –  for use on VIP Go projects
• WordPressVIPMinimum – for use on WordPress.com projects

Although these are based upon the standard WordPress rulesets, and have strengthened sniffs for security and performance, some of the more, shall we say, pernickety sniffs are left out, so you’ll be bugged less about spacing of comments, for example. An assumption is made at this point of the base level of development experience of anybody writing using this particular ruleset.

If you use these rulesets, you’ll find that they may include actions to use alternative VIP functions. Why would you use these? Well, any VIP client will be required to do so, so making your plugin fully VIP compatible means that it may attract the interest of Enterprise-level users. It’s a nice thing to boast of – both the VIP compatibility and the users of your plugin.

Of course, these new functions (you can find details about them on the VIP site) won’t work for non-VIP sites, so you may need to add in a detection routine and use whichever is most relevant to your user. For example, if you use wp_remote_get, you’ll be prompted to use vip_safe_wp_remote_get instead. You can implement it like this…

if ( function_exists( 'vip_safe_wp_remote_get' ) ) {
    $response = vip_safe_wp_remote_get( $source, '', 3, 3 );
} else {
    $response = wp_remote_get( $source, array( 'timeout' => 3 ) ); // @codingStandardsIgnoreLine -- for non-VIP environments
}

Note the comment on the end of the wp_remote_get line – this is telling PHPCS to ignore errors for that line, which will continue to occur otherwise, due to your use of that function.

If you do wish to use the VIP rulesets, I’d recommend using the WordPress ruleset along with WordPress-VIP-Go.

Using PHPCS

Using PHPCS from the command line is actually quite easy and is better than using the editor in 2 situations…

• Verification of errors across a project, rather than a single file
• For automatically fixing some error

The basic command to run PHPCS will be something like this…

phpcs --standard=WordPress test-file.php

Where test-file.php is a file that exists in the current directory. You’ll see I’ve specified the ruleset as WordPress.

To get PHPCS to scan an entire folder, you would do something like this…

phpcs --standard=WordPress ~/folder/

Where ~/folder/is a relevant path to your code. This will scan all files and folders from this path and is useful for outputting any issues for an entire project.

As you can imagine, there are a lot more commands available, including the ability to change which priority of issue is shown. To list these all, simply type phpcs --help.

PHPCS has another trick up its sleeve – PHPCBF (PHP Code Beautifier and Fixer). Run this command and it will tidy up your code and fix some of the issues itself (those that it can do, anyway). I find this useful to run across a project at the beginning. So, to run across a folder you’d use…

phpcbf --standard=WordPress ~/folder/

Again, use phpcbf --help for a full list of parameters.

Ignoring parts of a file

There may be parts of your code that you may wish to suppress errors for – maybe a sniff is firing incorrectly or, as demonstrated earlier, you’ve actually corrected something but an error is still showing (it happens). In this case you can use PHP comments to tell PHPCS to ignore a single line or a group of lines.

For a group of lines, simply use // @codingStandardsIgnoreStart before them and // @codingStandardsIgnoreEnd after them.

To ignore a single line, add // @codingStandardsIgnoreLine to the end of the line.

In all cases, it is highly recommend that you add a comment after these to indicate your reasons why it’s been ignored – this is done with a double dash, like so…

// @codingStandardsIgnoreLine -- this is not a core file

Finally, but probably not recommended, is // @codingStandardsIgnoreFile, which can be used to force PHPCS to ignore everything within the file.