Advertisement
  1. Code
  2. Coding Fundamentals

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

Scroll to top
Read Time: 14 min

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.

Prerequisites

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 RulesThe WordPress Coding Standard RulesThe 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:

1
{
2
    "require": {
3
        "squizlabs/php_codesniffer": "2.*"
4
    }
5
}

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:

1
$ vendor/bin/phpcs --version

And you should see something like the following output:

1
PHP_CodeSniffer version 2.6.0 (stable) by Squiz (https://www.squiz.net)

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:

1
composer create-project wp-coding-standards/wpcs:dev-master --no-dev

Note that you may be prompted with the following question:

1
Do you want to remove the existing VCS (.git, .svn..) history? [Y,n]?

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:

1
$ vendor/bin/phpcs --config-set installed_paths wpcs

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:

1
$ vendor/bin/phpcs -i

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

1
The installed coding standards are MySource, PEAR, PHPCS, PSR1, PSR2, Squiz, Zend, WordPress, WordPress-Core, WordPress-Docs, WordPress-Extra and WordPress-VIP

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 DollyPreparing to test Hello DollyPreparing 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:

1
$ vendor/bin/phpcs --standard=WordPress hello-dolly

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

1
FILE: /Users/tommcfarlin/Desktop/tutsplus_demo/hello-dolly/hello.php
2
----------------------------------------------------------------------
3
FOUND 14 ERRORS AFFECTING 14 LINES
4
----------------------------------------------------------------------
5
  2 | ERROR | Missing short description in doc comment
6
  5 | ERROR | There must be exactly one blank line after the file
7
    |       | comment
8
  6 | ERROR | Empty line required before block comment
9
 15 | ERROR | You must use "/**" style comments for a function
10
    |       | comment
11
 46 | ERROR | Inline comments must end in full-stops, exclamation
12
    |       | marks, or question marks
13
 49 | ERROR | Inline comments must end in full-stops, exclamation
14
    |       | marks, or question marks
15
 53 | ERROR | Inline comments must end in full-stops, exclamation
16
    |       | marks, or question marks
17
 54 | ERROR | You must use "/**" style comments for a function
18
    |       | comment
19
 56 | ERROR | Expected next thing to be an escaping function (see
20
    |       | Codex for 'Data Validation'), not '"<p

21
    |       | id='dolly'>$chosen</p>"'
22
 59 | ERROR | Inline comments must end in full-stops, exclamation
23
    |       | marks, or question marks
24
 62 | ERROR | Inline comments must end in full-stops, exclamation
25
    |       | marks, or question marks
26
 63 | ERROR | You must use "/**" style comments for a function
27
    |       | comment
28
 64 | ERROR | Inline comments must end in full-stops, exclamation
29
    |       | marks, or question marks
30
 67 | ERROR | Expected next thing to be an escaping function (see
31
    |       | Codex for 'Data Validation'), not '"

32
    |       | '
33
----------------------------------------------------------------------

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:

1
<?php
2
/**

3
 * @package Hello_Dolly

4
 * @version 1.6

5
 */
6
/*

7
Plugin Name: Hello Dolly

8
Plugin URI: https://wordpress.org/plugins/hello-dolly/

9
Description: This is not just a plugin, it symbolizes the hope and enthusiasm of an entire generation summed up in two words sung most famously by Louis Armstrong: Hello, Dolly. When activated you will randomly see a lyric from <cite>Hello, Dolly</cite> in the upper right of your admin screen on every page.

10
Author: Matt Mullenweg

11
Version: 1.6

12
Author URI: http://ma.tt/

13
*/
14
15
function hello_dolly_get_lyric() {
16
    /** These are the lyrics to Hello Dolly */
17
	$lyrics = "Hello, Dolly

18
Well, hello, Dolly

19
It's so nice to have you back where you belong

20
You're lookin' swell, Dolly

21
I can tell, Dolly

22
You're still glowin', you're still crowin'

23
You're still goin' strong

24
We feel the room swayin'

25
While the band's playin'

26
One of your old favourite songs from way back when

27
So, take her wrap, fellas

28
Find her an empty lap, fellas

29
Dolly'll never go away again

30
Hello, Dolly

31
Well, hello, Dolly

32
It's so nice to have you back where you belong

33
You're lookin' swell, Dolly

34
I can tell, Dolly

35
You're still glowin', you're still crowin'

36
You're still goin' strong

37
We feel the room swayin'

38
While the band's playin'

39
One of your old favourite songs from way back when

40
Golly, gee, fellas

41
Find her a vacant knee, fellas

42
Dolly'll never go away

43
Dolly'll never go away

44
Dolly'll never go away again";
45
46
	// Here we split it into lines

47
	$lyrics = explode( "\n", $lyrics );
48
49
	// And then randomly choose a line

50
	return wptexturize( $lyrics[ mt_rand( 0, count( $lyrics ) - 1 ) ] );
51
}
52
53
// This just echoes the chosen line, we'll position it later

54
function hello_dolly() {
55
	$chosen = hello_dolly_get_lyric();
56
	echo "<p id='dolly'>$chosen</p>";
57
}
58
59
// Now we set that function up to execute when the admin_notices action is called

60
add_action( 'admin_notices', 'hello_dolly' );
61
62
// We need some CSS to position the paragraph

63
function dolly_css() {
64
	// This makes sure that the positioning is also good for right-to-left languages

65
	$x = is_rtl() ? 'left' : 'right';
66
67
	echo "

68
	<style type='text/css'>

69
	#dolly {

70
		float: $x;

71
		padding-$x: 15px;

72
		padding-top: 5px;		

73
		margin: 0;

74
		font-size: 11px;

75
	}

76
	</style>

77
	";
78
}
79
80
add_action( 'admin_head', 'dolly_css' );
81
82
?>

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:

1
<?php
2
/**

3
 * This is a plugin that symbolizes the hope and enthusiasm of an entire

4
 * generation summed up in two words sung most famously by Louis Armstrong.

5
 *

6
 * @package Hello_Dolly

7
 * @version 1.6

8
 *

9
 * @wordpress-plugin

10
 * Plugin Name: Hello Dolly

11
 * Plugin URI: https://wordpress.org/plugins/hello-dolly/

12
 * Description: This is not just a plugin, it symbolizes the hope and enthusiasm of an entire generation summed up in two words sung most famously by Louis Armstrong: Hello, Dolly. When activated you will randomly see a lyric from <cite>Hello, Dolly</cite> in the upper right of your admin screen on every page.

13
 * Author: Matt Mullenweg

14
 * Version: 1.6

15
 * Author URI: http://ma.tt/

16
 */
17
18
/**

19
 * Defines the lyrics for 'Hello Dolly'.

20
 *

21
 * @return string A random line of from the lyrics to the song.

22
 */
23
function hello_dolly_get_lyric() {
24
    /** These are the lyrics to Hello Dolly */
25
    $lyrics = "Hello, Dolly

26
Well, hello, Dolly

27
It's so nice to have you back where you belong

28
You're lookin' swell, Dolly

29
I can tell, Dolly

30
You're still glowin', you're still crowin'

31
You're still goin' strong

32
We feel the room swayin'

33
While the band's playin'

34
One of your old favourite songs from way back when

35
So, take her wrap, fellas

36
Find her an empty lap, fellas

37
Dolly'll never go away again

38
Hello, Dolly

39
Well, hello, Dolly

40
It's so nice to have you back where you belong

41
You're lookin' swell, Dolly

42
I can tell, Dolly

43
You're still glowin', you're still crowin'

44
You're still goin' strong

45
We feel the room swayin'

46
While the band's playin'

47
One of your old favourite songs from way back when

48
Golly, gee, fellas

49
Find her a vacant knee, fellas

50
Dolly'll never go away

51
Dolly'll never go away

52
Dolly'll never go away again";
53
54
	// Here we split it into lines.

55
	$lyrics = explode( "\n", $lyrics );
56
57
	// And then randomly choose a line.

58
	return wptexturize( $lyrics[ mt_rand( 0, count( $lyrics ) - 1 ) ] );
59
}
60
61
add_action( 'admin_notices', 'hello_dolly' );
62
/**

63
 * This just echoes the chosen line, we'll position it later. This function is

64
 * set up to execute when the admin_notices action is called.

65
 */
66
function hello_dolly() {
67
68
	$chosen = hello_dolly_get_lyric();
69
	echo "<p id='dolly'>$chosen</p>"; // WPCS: XSS OK.

70
71
}
72
73
add_action( 'admin_head', 'dolly_css' );
74
/**

75
 * Add some CSS to position the paragraph.

76
 */
77
function dolly_css() {
78
79
	/**

80
	 *This makes sure that the positioning is also good for right-to-left languages.

81
	 */
82
	$x = is_rtl() ? 'left' : 'right';
83
	echo "<style type='text/css'> #dolly { float: $x; padding-$x: 15px; padding-top: 5px; margin: 0; font-size: 11px; } </style> "; // WPCS: XSS OK.

84
85
}

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.

1
$ vendor/bin/phpcs --standard=WordPress hello-dolly

And the output that we see:

1
Skyhopper5:tutsplus_demo tommcfarlin$

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.

Conclusion

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.

Resources

Advertisement
Did you find this post useful?
Want a weekly email summary?
Subscribe below and we’ll send you a weekly email summary of all new Code tutorials. Never miss out on learning about the next big thing.
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.