Every developer worth his or her weight will say writing quality code is key to making sure a project is maintainable over time.

What constitutes quality code may be subjective and this is not the post to debate that; however, if you’re working with PHP – especially alongside MAMP and WordPress – then I think using the PHP CodeSniffer is a tool we should all be using.

For those who’ve written both PHP applications and WordPress-specific applications, you know there are different standards used for writing code. Since this blog is primarily focused on the latter, then I’m obviously going to be focusing on that, but the steps provided aren’t altogether different for working strictly with PHP.

So here’s how you can setup PHP CodeSniffer, the rules for the WordPress Coding Standards, and how to have them run alongside MAMP.

PHP CodeSniffer, MAMP, and WordPress

If you’re familiar with a linter (such as JSLint or JSHint), then you’re familiar with the concept of a code sniffer. In short:

PHP_CodeSniffer tokenizes PHP, JavaScript and CSS files and detects violations of a defined set of coding standards.

You don’t have to run it against JavaScript and CSS especially if you’re already using tools like Sass and JSHint, but if you aren’t then it may be helpful.

Anyway, the nice thing is there’s a version of the project that’s available for WordPress. Its goal:

PHP_CodeSniffer rules to enforce WordPress coding conventions

Nice!

Unfortunately, setting it up is a little bit cumbersome so I thought I’d provide a set of steps to follow when setting all of this up.

Before going any further, I’m assuming you already have browser tabs open for:

  1. PHP CodeSniffer on GitHub
  2. WordPress-Coding-Standards on GitHub

And you’re running MAMP and are using at least PHP 5.5.26 in your installation (though you really can be running any version – just pay close attention to the commands later in the article).

1. Using Pear

Pear is an extension an application repository for PHP that makes it easy to install packages you may not already have installed.

If you’re working in Linux or OS X then there’s a chance your system is not setup the version of Pear that’s included with your copy of MAMP. To fix this, we need to update an environmental path so it references the version of Pear that’s included with the version of Pear corresponding to the version of PHP you’re using.

As mentioned in the case above, if you’re using PHP 5.5.26, then this will be located in that particular directory on your machine.

To locate it, enter the following commands from the root of your system into your Terminal session:

$cd Applications/MAMP/bin/php/php5.5.26/bin

In this directory, you should find pear (which you can list by listing out the contents of the directory using the ls command):

Where's Pear?

Next, add this copy of Pear to your environmental variables so it’s used in place of whatever other copy of Pear is being used through your system. To do this, we need to add the location of this copy of Pear to your .profile.

Not too bad. Just enter the following command in the Terminal:

$ echo "export PATH=/Applications/MAMP/bin/php/php5.5.26/bin:$PATH"  >> ~/.profile

This will write the path of the directory we’re currently in to the .profile associated with your account. At this point, you should be able to run $ which pear and see the file being referenced is the one in the MAMP directory.

If not, open .profile and make sure the directory you’re currently in is at the very beginning of the file.

2. Installing PHP CodeSniffer

There are a few ways to go about doing this, but since I just walked through the whole process of setting up pear, then that’s the route I’m opting to take (others include using Composer).

PHP CodeSniffer

To install the package, enter the following command into the Terminal:

$ pear install PHP_CodeSniffer

And this will begin downloading the package and installing it on your system. Once done, we’re ready to install the sniffer for the WordPress Coding Standards.

3. Installing The WordPress Coding Standards Rules

Assuming the previous installation went well, the next thing to do is to install and configure the rules for the WordPress Coding Standards.

PHP Coding Standards

Here’s the thing: It’s not located in the Pear repository so we’ll have to use the Git repository in order to do it. This assumes you have Git installed on your system (if not, it’s easy to do).

If you’re like me, then you like to keep your directories organized with a specific scheme to help manage your files. To that end, think about where you want the WordPress rules downloaded.

It doesn’t really matter since the rules will be added to the PHP CodeSniffer; however, I consider it an add-on to the PHP CodeSniffer so wherever that extension has been installed is where I’d also like to install the WordPress Coding Standards sniffer.

You can find this by running $ which phpcs in your Terminal, but since we were just in the bin directory of our version of PHP, then we’re good to go. So run the following command:

$ git clone git@github.com:WordPress-Coding-Standards/WordPress-Coding-Standards.git wpcs

This will clone a copy of the repository to a directory called wpcs in the directory out of which we’re currently working. Next, change directories into the wpcs directory and then specify the command for the current working directory of the WordPress Coding Standards. This will likely look something like:

/Applications/MAMP/bin/php/php5.5.26/bin/wpcs.

From there, we need to add the rules to the PHP CodeSniffer to issue the following command:

$ phpcs --config-set installed_paths /Applications/MAMP/bin/php/php5.5.26/bin/wpcs

At this point, you should be good to go, but to verify it run $ phpcs -i and you should be presented with the following screen:

Installed Paths

Notice towards the end, you’ll see all of the available WordPress rules.

4. Testing The Installation

To test the installation, navigate to a WordPress plugin directory in your local install. Let’s say we want to sniff one of the files in the Hello Dolly plugin.

Locate a copy of wp-content/plugins/ and then enter the following command which targets hello.php:

$ phpcs --standard=WordPress hello.php

And you should see the following output:

Hello Dolly Errors

Notice the generated table produces the line number, the error, and what should be done to fix the code.

Using The Coding Standards

I’m a big fan of the Coding Standards and think we should do all we can to adhere to them when working with our projects. This also includes linting our JavaScript and so on.

Granted, it might make project development more time-consuming but, in my mind, quality is worth it.

The best advice I can offer is to run this after working through a given file rather than waiting until the very end in order to go back and work through all the errors that may appear once the project is done.

Category:
Resources
Tags:
,

Join the conversation! 15 Comments

  1. Tom,

    Thanks for this tutorial. I have been digging around on how to get this to work for a while now.

    Is there a way to export the report rather than view in command-line?

    The idea is to slowly fix all my plugin files, though it will be time consuming given they are all done right now…

    • I appreciate the instructions here, but I would not use PEAR for this. You can install this either directly via homebrew or the alternative you suggest, composer global. If you’re running a command line utility like phpcs, you don’t strictly need to use MAMPs PHP version to handle this stuff, as OSX comes with PHP preinstalled, so you can just use the system’s version.

      PEAR is really old/outdated, and a number of PHP libraries are pulling themselves off of it, most importantly being PHPUnit (https://github.com/sebastianbergmann/phpunit/wiki/End-of-Life-for-PEAR-Installation-Method). I wouldn’t rely on PEAR for installing PHP packages at all going forward.

      That said, I do love me some PHP CodeSniffer and definitely like to see more people advocating for its use!

      • I appreciate the instructions here, but I would not use PEAR for this.

        You can install this either directly via homebrew or the alternative you suggest, composer global. If you’re running a command line utility like phpcs, you don’t strictly need to use MAMPs PHP version to handle this stuff, as OSX comes with PHP preinstalled, so you can just use the system’s version.

        Thanks for following up with information on Composer. Maybe I’ll do a follow-up post that walks through how to use it instead of Pear for those who want to use more recent tools.
        True – this doesn’t have to be done with MAMP but since most people have some type of development environment setup, I opted to go with it (also because I use it :), but many of the instructions work just as well with whatever version of PHP you have installed.

    • Yes, you can use any of the reporting methods found in their repo, one of which is a codestyle report in HTML:

      https://github.com/squizlabs/PHP_CodeSniffer/wiki/Reporting

    • Is there a way to export the report rather than view in command-line?

      Yep – you can use the ‘>’ operator in the command line to place the output into a file. The structure of the command is like this:

      $ phpcs your-file.php > output.txt

      And you should be good to go.

  2. Once you have PHP Code Sniffer running with Pear you can also integrate it with Grunt (https://www.npmjs.com/package/grunt-phpcs) there is also a few ways to do it with Gulp (https://www.npmjs.com/package/grunt-phpcs, or https://www.npmjs.com/package/gulp-phpcs).

    Though I’ve been working Brackets from Adobe (www.brackets.io) for the past few months, and it has PHP Code Sniffer built-in and includes the WordPress standards that can be enabled. The errors then show up in a docked panel at the bottom of the coding area. Brackets also has a number of extensions for auto-complete for WordPress core code, functions, query etc.

    Either way you do it though PHP Code Sniffer is a great way to ensure you are writing quality code!

  3. Should note that after changing your .profile file you should logout/login or source the file to have the results in your current shell.

    PhpStorm also has some support for Code Sniffer, but I haven’t taken the time to try it out yet.

    • Should note that after changing your .profile file you should logout/login or source the file to have the results in your current shell.

      Good point – thanks for mentioning this.

      PhpStorm also has some support for Code Sniffer, but I haven’t taken the time to try it out yet.

      I personally don’t use PHPStorm but I know a lot of people who do, so having it available in the IDE is nice.

      — Tom

  4. Hey Tom – thanks for writing this. I thought I was quite good with the WP coding standards but I’ve just gone through and set it all up and it’s shown me quite a few things I wasn’t aware of! :)

    In doing it I noticed a few things that were wrong with your article.

    1) some of the code samples don’t display properly

    2) you’re missing a space in the phpcs config-set command between install_paths and the path. This caught me out for a while :)

    3) a general comment – I found it easier to git clone from the https url as I don’t have the gitup ssh certificates setup since I normally use the github visual client.

    Either way – really interesting and glad I set it up

    • 1) some of the code samples don’t display properly

      Meh. That’s encoding. I’ll take care of that (again :). Thanks for the heads up!

      2) you’re missing a space in the phpcs config-set command between install_paths and the path. This caught me out for a while :)

      Noted and will be fixed! Good catch and my bad on missing it.

      3) a general comment – I found it easier to git clone from the https url as I don’t have the gitup ssh certificates setup since I normally use the github visual client.

      Not a bad note to have here. I’m also planning a follow up on how to use Composer to install this, well. When I draft that article, I’ll see about mentioning this comment in the post, as well.

  5. Hi Tom, it’s very nice of you. Now I am facing some problems after installed PHPCS by pear, and the problems are like this:

    PHP Warning: include_once(PHP/CodeSniffer/autoload.php): failed to open stream: No such file or directory in /usr/local/bin/phpcs on line 14

    PHP Warning: include_once(): Failed opening ‘PHP/CodeSniffer/autoload.php’ for inclusion (include_path=’.:’) in /usr/local/bin/phpcs on line 14

    PHP Fatal error: Class ‘PHP_CodeSniffer\Runner’ not found in /usr/local/bin/phpcs on line 17

    I don’t know why it always claims these fault when I run ‘phpcs blabla.php’. Looking forward to your reply.

    • Hey Steve,

      These messages usually mean that the installation of PHPCS wasn’t successful.

      • If you do an ls /usr/local/bin, do you see PHPCS in the directory?
      • Further, in the terminal, if you run phpcs -i, do you get any information back?

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.