It's Friday - what a day to visit jfoobar!

Continuous Integration in PHP; a closer look at coding standards

Written by Wilco Jansen Tuesday, 08 September 2009 15:49

In the examples of this article I use a local exported version of the Joomla development trunk (revision 12681), which currently holds the latest work in progress for Joomla 1.6. Before we can start the actual analyses we install the PHP codesniffer. Make sure you have PEAR installed and installation is no more work then the following command:

pear install PHP_CodeSniffer

In the examples I have installed the latest version of PHP codesniffer version 1.2.0RC3. The tools works from the command line and has various options, a short overview:

Usage: phpcs [-nwlsvi] [--report=<report>] [--report-file=<reportfile>]
    [--config-set key value] [--config-delete key] [--config-show]
    [--standard=<standard>] [--sniffs=<sniffs>]
    [--extensions=<extensions>] [--ignore=<patterns>]
    [--generator=<generator>] [--tab-width=<width>] <file> ...
        -n           Do not print warnings
        -w           Print both warnings and errors (on by default)
        -l           Local directory only, no recursion
        -s           Show sniff codes in all reports
        -v[v][v]     Print verbose output
        -i           Show a list of installed coding standards
        --help       Print this help message
        --version    Print version information
        <file>       One or more files and/or directories to check
        <extensions> A comma separated list of file extensions to check
                     (only valid if checking a directory)
        <patterns>   A comma separated list of patterns that are used
                     to ignore directories and files
        <sniffs>     A comma separated list of sniff codes to
                     limit the check to (all sniffs must be
                     part of the specified standard)
        <standard>   The name of the coding standard to use
        <width>      The number of spaces each tab represents
        <generator>  The name of a doc generator to use
                     (forces doc generation instead of checking)
        <report>     Print either the "full", "xml", "checkstyle",
                     "csv", "emacs", "source" or "summary" report
                     (the "full" report is printed by default)
        <reportfile> Write the report to the specified file path
                     (report is also written to screen)

In this article I will not handle all options, but just give an example on what is required to use the tool, and make the code PEAR compliant. Lets start with an easy example, we take the "index.php" file that resides in the root of the trunk. We trigger the command (see example below), and this gives us the following output:

phpcs --standard=PEAR index.php

FILE: /var/www/export/trunk/index.php
--------------------------------------------------------------------------------
FOUND 10 ERROR(S) AND 3 WARNING(S) AFFECTING 5 LINE(S)
--------------------------------------------------------------------------------
 3 | WARNING | Invalid version "$Id: index.php 12490 2009-07-06 11:57:32Z
   |         | eddieajau $" in file comment; consider "CVS: <cvs_id>" or "SVN:
   |         | <svn_id>" instead
 3 | ERROR   | There must be exactly one blank line before the tags in file
   |         | comment
 3 | ERROR   | The @version tag is in the wrong order; the tag follows @license
 3 | ERROR   | @version tag comment indented incorrectly. Expected 3 spaces but
   |         | found 0.
 4 | ERROR   | @package tag comment indented incorrectly. Expected 3 spaces but
   |         | found 0.
 5 | WARNING | Line exceeds 85 characters; contains 86 characters
 5 | ERROR   | @copyright tag must contain a year and the name of the copyright
   |         | holder
 5 | ERROR   | @copyright tag comment indented incorrectly. Expected 1 spaces
   |         | but found 0.
 6 | ERROR   | @license tag comment indented incorrectly. Expected 3 spaces but
   |         | found 0.
 7 | WARNING | PHP version not specified
 7 | ERROR   | Missing @category tag in file comment
 7 | ERROR   | Missing @author tag in file comment
 7 | ERROR   | Missing @link tag in file comment
--------------------------------------------------------------------------------

You instantaneously see that 80% of the DocBook markups is marked invalid. Something that is pretty easy to fix. The PHP codesniffer tool also has an option to create a report summary, and also traverse through all sub-directories, let us examine the state of the Joomla code-base, we limit ourselves to the application framework classes (libraries/joomla). Even with the summary switch enabled this gives a long list of violations, we will share the beginning and ending of the generated output.

phpcs --standard=PEAR --report=summary --extensions=php trunk/libraries/joomla/

PHP CODE SNIFFER REPORT SUMMARY
--------------------------------------------------------------------------------
FILE                                                            ERRORS  WARNINGS
--------------------------------------------------------------------------------
/var/www/export/trunk/libraries/joomla/html/html/jgrid.php      115     10
/var/www/export/trunk/libraries/joomla/html/html/content.php    63      4
/var/www/export/trunk/libraries/joomla/html/html/grid.php       430     18
.
.
.
...export/trunk/libraries/joomla/installer/librarymanifest.php  113     10
/var/www/export/trunk/libraries/joomla/installer/extension.php  101     3
/var/www/export/trunk/libraries/joomla/import.php               16      3
--------------------------------------------------------------------------------
A TOTAL OF 87340 ERROR(S) AND 2356 WARNING(S) WERE FOUND IN 234 FILE(S)
--------------------------------------------------------------------------------

Wow! That is a lot of violations in only 234 files, looks like there is a lot of work to do on this area ;-) Of course there are some false positives since some of those files contain a mixture of (X)HTML and PHP (for example the installer views), but it is clearly that there is a problem with the implementation of the coding standards, even when you define a specific set of validation rules for Joomla (I experimented a bit with these rules). Something to consider fixing by the current development team...

PHP codesniffer has multiple options, and one of them is also defining your own set of coding standards, lets try the same with the Zend libraries (stable release 1.9.2 has been used).

phpcs --standard=Zend --report=summary --extensions=php Zend/

No surprise that this lead to no errors since Zend is a good example of a project that uses these tools for their development process. You can do a simple test with the zend code and replace the validation rules from Zend to PEAR...always fun to see how many error we will see then.

We now have taken a very brief look at the PHP codesniffer tool. The tool helps you validate if code has been written according to the coding guidelines. In the next article we will take a brief look at another tool used within continuous building, and how it can be put to work for you. Remember that PHP codesniffer does not limit you when you use a different set of coding guidelines, you only will need to put some serious effort into the rule engine of the tool. Not always an easy task and before you do make sure the coding standards have a final status.

A final word on the use of tools like these...a fool with a tool is still a fool. In this particular context I strongly advise not to rely only on tools like this. Common best practices like software peer reviews can be applied with common sense. Keep in mind that the end goals should be high quality software, with the lowest possible costs for maintenance (since this is around 80% of the total costs of a software product).

Like it? Share it!

• bookmark.it
• del.icio.us
• digg
• furl
• blinkllist
• reddit
• feedmelinks
• technorati
• yahoo
• rawsugar
• netvouz
• rojo
• shadows
• gabbr
• dzone
• newsvine
• ma.gnolia
• stumbleupon
• google
• squidoo
• spurl
• blinkbits
• blogmarks
• bloglines
• co.mments
• scuttle
• ask
• slashdot