1. Code
  2. PHP

Using PHP CodeSniffer With WordPress: Installing and Using the WordPress Rules


If you're just joining the series, we've been discussing the topic of code smells, how to refactor them, and tools that are available to help us automate some of the monotony that comes with doing so, especially within PHP programming.

If you've not read the first two articles in the series, I recommend it as they cover a few prerequisites we have in place before moving forward with the remainder of the article.

The articles are:

  1. Using PHP CodeSniffer With WordPress: Understanding Code Smells
  2. Using PHP CodeSniffer With WordPress: Installing and Using PHP CodeSniffer

In short, the articles above will introduce the concept of code smells, which we've been defining as the following:

[A] code smell, also known as a bad smell, in computer programming code, refers to any symptom in the source code of a program that possibly indicates a deeper problem. 

And I will walk you through the steps needed to install PHP CodeSniffer on your machine.

But if you've made it this far, I assume you're a WordPress developer, and you're interested in getting PHP CodeSniffer configured such that it can sniff out any problems in your code as it relates to the WordPress Coding Standards.

That's good! Because in the remainder of this article, that's exactly what we're going to cover.


This should be a very short list. If you've followed along with the series up to this point, you need to have:

All of this is covered in detail throughout the previous articles in the series, but if you've gotten this far and are comfortable with the command line then this should be a cinch in comparison to what we've done so far.

With all of that said, let's get started.

The WordPress Rules for PHP CodeSniffer

First, locate the WordPress Coding Standards rules on GitHub. They're easy to find.

The WordPress Coding Standard Rules

You can read all about the details of the project from the project page, but the most important thing I'd like to share is as follows:

This project is a collection of PHP_CodeSniffer rules (sniffs) to validate code developed for WordPress. It ensures code quality and adherence to coding conventions, especially the official WordPress Coding Standards.

I'd like to bring your attention to the phrase that this references the "official WordPress Coding Standards." Note that these rules are based on the WordPress Coding Standards. That is, you can't officially reference them.

If you're looking to find a way to look through the rules that WordPress defines, check out this article in the Codex. It's easy to follow, easy to read, but a lot to remember. Thankfully, we have the rule set linked above.

The important thing to note is that even if you aren't familiar with the rules, the CodeSniffer will find the problems with your code and will notify you of what you need to fix. Though you don't have to read the Codex article, it can sometimes help in identifying what's needed based on the errors or warnings the sniffer generates.

1. Install the WordPress Rules

Assuming you've properly installed PHP CodeSniffer, let's add the WordPress rules to the software. For this tutorial, I'm going to do everything via the command line so as to be as platform agnostic as possible. I'll offer a few words regarding IDEs and rules at the end of the series.

Open your Terminal and navigate to where you have your copy of PHP CodeSniffer installed. If you've been following along with this series of tutorials, then you likely recall we have a composer.json file that will pull this in for us. If not, remember to create composer.json in the root of your project and add this to the file:

Once done, run $ composer update from your Terminal and you'll have everything you need to get going. To verify the installation, run the following command:

And you should see something like the following output:

Perfect. Next, let's install the WordPress rules. Since we're using Composer (and will continue to do so), this is very easy to do.

Run the following command from within the root directory of your project:

Note that you may be prompted with the following question:

If you know what you're doing, then feel free to go ahead and select 'n'; otherwise, you'll be fine hitting 'y'.

2. Add the Rules to PHP CodeSniffer

Now that PHP CodeSniffer is installed, and the WordPress rules are installed, we need to make sure PHP CodeSniffer is aware of our new ruleset. To do this, we need to enter the following command in the command line. 

From the root of your project directory, enter the following command:

To verify that the new rules have been added, we can ask PHP CodeSniffer to report to us the sets of rules that it currently has available. In the Terminal, enter the following command:

And you should see the following output (or something very similar):

Notice in the line above that we have several sets of rules regarding WordPress. Pretty neat, isn't it? Of course, let's see how this stacks up when we run the rule sets against a plugin like Hello Dolly.

3. Running PHP CodeSniffer Against WordPress Projects

Assuming you're working out of a directory that includes a WordPress plugin, then you can skip the following step. If, on the other hand, you do not have a copy of a WordPress script, file, theme, or plugin installed in the project directory, go ahead and copy one over to your project directory now.

As mentioned, we'll be testing the Hello Dolly plugin.

Preparing to test Hello Dolly

To run PHP CodeSniffer with the WordPress rules against the files in the plugin directory, enter the following command in the Terminal:

This will result in output that should correspond to what you see here:

Of course, some of these things may change depending on when you're reading this tutorial.

The errors should be pretty clear as to what needs to be fixed:

  • The first column denotes the line in which the problem exists.
  • The second column determines if there is an error or a warning.
  • The third column explains the problem and what's expected of the code.

Note that although these are errors or warnings, the code will obviously still work. But let's pull this through end-to-end and see what it's like to fix up a plugin, arguably the most popular since it comes with each installation of WordPress, and review the differences in the quality of the code.

4. Refactoring Hello Dolly

Note the plugin, before we begin working on it, includes the following source code:

It should be relatively easy to follow as it uses only a few basic PHP features and Matt's done a good job of commenting the code.

But given the 14 errors that the CodeSniffer found, let's refactor the plugin. Taking into account the errors they presented and what it's expecting to see, let's address each of them.

Once done, the plugin should look like the following:

Notice that the plugin continues to work and the code is a bit cleaner. Lastly, let's verify that this passes the PHP CodeSniffer test. Let's re-run the code that we used above to initially evaluate the plugin.

And the output that we see:

Exactly: There should be no output. Instead, it should be a return to the standard command prompt.

Excellent. The plugin has been brought up to standard. This is why having a code sniffer is so valuable: It finds the errors in your code based on the rules you define and then reports any errors that may exist.

Ultimately, this ensures that you're releasing the highest quality written code into a production-level site. Now, this does not mean you should avoid unit testing or other types of testing, nor does this mean bugs don't exist. It just means that your code is up to a high standard.


And with that, we conclude the series on using PHP CodeSniffer. Recall that throughout the series, we have covered the idea of code smells, how to refactor them, and what tools are available to us when working with PHP applications.

In this article, we saw how we can use a provided set of rules for the WordPress Coding Standards to evaluate our code while working on a new or an existing project. Note that some IDEs support the ability to execute the rules while writing code.

Although that's beyond the scope of this particular tutorial, you can find resources for this in various places throughout the web. Simply search for your IDE by name, determine its support for PHP CodeSniffer, and then make sure to install the WordPress rules as we've detailed in this tutorial.

If you enjoyed this article or this series, you might be interested in checking out other things I've written both on my profile page or on my blog. You can also follow me on Twitter at @tommcfarlin where I often talk about and share various software development practices within the context of WordPress.

With that said, don't hesitate to leave any questions or comments in the feed below and I'll aim to respond to each of them.


Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.