Sunday, July 17, 2011

Quality Assurance on PHP projects - PHP_CodeSniffer

PHP_CodeSniffer is probably the most convenient tool out there to analyze your source code and to verify it complies to company policies. Although it's debatable why source code should follow strict guidelines, it's only a matter of time before you discover yourself that it pays off to have a code base that appears to be written by one developer.

The first question you have to ask is what standard are you going to implement. There are several standards already packaged with PHP_CodeSniffer, but are they useful within your company? Maybe you want to extend or override some standards with your own implementation. Do remember, the standards supplied with PHP_CodeSniffer have been negotiated over and over by the developers for ages. So if you want to define your own standards, be warned that it can be a long and tedious track before you can agree on a specific standard.

Installing PHP_CodeSniffer is easy when using the PEAR framework. Make sure you have installed and upgraded the pear libraries that come with your OS. After that all you need to do as root or Administrator is the following.

user@server: $ pear install PHP_CodeSniffer

Or you can go to the download page of PHP_CodeSniffer and download the source package yourself and install it the way you want it. In most cases, the PEAR installation is a more elegant, easy way to install the tool.

Configuration & Execution
PHP_CodeSnifferdoesn't require much configuration, but you have to decide on which coding standard you want to check the code base.

Standards provided by PHP_CodeSniffer are the following:
  • Zend
  • PEAR
  • Squiz
  • MySource
user@server: phpcs --standard=PEAR /path/to/php/sources

But as stated, you can also define your own standard and provide the base path of the repository on command line

user@server: phpcs --standard=/path/to/my/standards /path/to/php/sources

There are a lot of extra options provided with this tool, but let me focus here on the more important ones you might find useful in your day-to-day usage of PHP_CodeSniffer.

Ignoring files and paths
If you have a couple of external libraries or test scripts in your PHP projects, you might want to exclude them because they're not really part of your concerns. Wouldn't it be easy to just exclude them from the analysis? The following command will exclude paths you have no interest in.

user@server: phpcs --standard=PEAR --ignore=*/tests/*,*/library/Zend/*

Output options
Sometimes you require a different report than the default report that covers all information. Maybe you require a simple summary, a blame report, source report or a report formatted in XML or CSV for usage in another tool. It's only one option away.

The summary report:
user@server: phpcs --standard=PEAR --report=summary

The blame report (requires project to be checked out from a Subversion server):
user@server: phpcs --standard=PEAR --report=svnblame

More on these report formats can be found on the documentation pages of PHP_CodeSniffer.

Running PHP_CodeSniffer on the command line is a very convenient way to investigate if the source code is following the standards everyone has agreed upon. 

You can also set it as a pre-commit hook for your revision control system, but in my experience it has a negative effect on the productivity of the development team. But it never hurts to try it out and see for yourself if it's a positive step or causes frustrations. A full description on how to set it up for Subversion is explained on the SVN pre-commit page of PHP_CodeSniffer.

When you want to ensure everyone on your team follows the standard policies of your department or company, PHP_CodeSniffer is a great tool to identify where developers need to modify their code so it complies.

Creative Commons License
This work is licensed under a Creative Commons Attribution-Noncommercial-No Derivative Works 3.0 License.