King Kludge

Continuing from Part 1: Introduction to CodeSniffer this time looking at and interpreting the output from CodeSniffer.

If we take an example block of code such as the following.

 
 
<?php

function DoSomething(array $foo) {
    print_r($foo);
}

?>
 

And run it through CodeSniffer with the Zend coding standard we get:

$ phpcs --standard=Zend foo.php

FILE: /home/bob/sample/foo.php
--------------------------------------------------------------------------------
FOUND 2 ERROR(S) AND 1 WARNING(S) AFFECTING 2 LINE(S)
--------------------------------------------------------------------------------
 2 | ERROR   | End of line character is invalid; expected "\n" but found "\r\n"
 4 | ERROR   | Opening brace should be on a new line
 4 | WARNING | Consider putting global function "DoSomething" in a static class
--------------------------------------------------------------------------------

If we then run the same code through the PHPCS standard we get a more in-depth set of violations:

$ phpcs --standard=PHPCS foo.php

FILE: /home/bob/sample/foo.php
--------------------------------------------------------------------------------
FOUND 16 ERROR(S) AND 2 WARNING(S) AFFECTING 6 LINE(S)
--------------------------------------------------------------------------------
 2 | ERROR   | End of line character is invalid; expected "\n" but found "\r\n"
 2 | ERROR   | End of line character is invalid; expected "\n" but found "\r\n"
 2 | ERROR   | Additional whitespace found at start of file
 3 | ERROR   | Missing file doc comment
 4 | WARNING | Consider putting global function "DoSomething" in a static class
 4 | ERROR   | Missing function doc comment
 4 | ERROR   | Function name "DoSomething" is invalid; consider "doSomething"
   |         | instead
 4 | ERROR   | Expected "function abc(...)\n"; found "function abc(...) "
 4 | ERROR   | Function name "DoSomething" is not in camel caps format
 4 | ERROR   | Expected 2 blank lines before function; 1 found
 4 | ERROR   | Opening brace should be on a new line
 4 | ERROR   | Opening brace should be on a new line
 4 | ERROR   | Opening brace should be on a new line
 5 | WARNING | The use of function print_r() is discouraged
 6 | ERROR   | Expected //end DoSomething()
 6 | ERROR   | Expected 1 blank line before closing function brace; 0 found
 6 | ERROR   | Expected 2 blank lines after function; 1 found
 8 | ERROR   | Additional whitespace found at end of file
--------------------------------------------------------------------------------

Hopefully you can see that the PHPCS standard is significantly more strict that the previous.

Also you should see that apart from more style based checks, this standard also checks for whitespace at the beginning and end of the file. Whitespace being echoed can be very important for some PHP frameworks. When lots of files are included as part of the execution, especially if they are dynamically loaded, the whitespace can cause a fatal error if header information is also being sent to the browser.

The other issues contained in this report are based around the project code layout and documentation requirements.

Other reports

With the release of CodeSniffer 1.2.x there are some new reporting types available.

Rather than the full in-depth report, two reports that I find quite useful for gauging a project’s status are the summary and source reports.

Summary reports the number of errors and warnings found on a file by file basis over a directory tree.

$ phpcs --report=summary --standard=Zend ./_rr

PHP CODE SNIFFER REPORT SUMMARY
--------------------------------------------------------------------------------
FILE                                                            ERRORS  WARNINGS
--------------------------------------------------------------------------------
.../yocal/apps/frontend/modules/_rr/templates/_partial_rr1.php  23      3
...yocal/apps/frontend/modules/_rr/templates/_partial_rr10.php  4       1
...yocal/apps/frontend/modules/_rr/templates/_partial_rr11.php  7       4
.../yocal/apps/frontend/modules/_rr/templates/_partial_rr2.php  8       2
.../yocal/apps/frontend/modules/_rr/templates/_partial_rr3.php  18      2
.../yocal/apps/frontend/modules/_rr/templates/_partial_rr4.php  43      3
.../yocal/apps/frontend/modules/_rr/templates/_partial_rr5.php  22      4
.../yocal/apps/frontend/modules/_rr/templates/_partial_rr6.php  39      3
.../yocal/apps/frontend/modules/_rr/templates/_partial_rr7.php  24      1
.../yocal/apps/frontend/modules/_rr/templates/_partial_rr8.php  17      2
...yocal/apps/frontend/modules/_rr/templates/_thumbsUpDown.php  71      4
--------------------------------------------------------------------------------
A TOTAL OF 276 ERROR(S) AND 29 WARNING(S) WERE FOUND IN 11 FILE(S)
--------------------------------------------------------------------------------

Source shows the  type of errors and warnings found in a project:

$ phpcs --report=source --standard=Zend ./_rr

PHP CODE SNIFFER VIOLATION SOURCE SUMMARY
--------------------------------------------------------------------------------
STANDARD    CATEGORY            SNIFF                                      COUNT
--------------------------------------------------------------------------------
Zend        Files               Line length                                92
Generic     White space         Disallow tab indent                        65
Zend        Naming conventions  Valid variable name                        59
PEAR        White space         Scope closing brace                        33
PEAR        Functions           Function call signature                    26
PEAR        Control structures  Control signature                          12
PEAR        Files               Line endings                               11
PEAR        Functions           Function call argument spacing             5
Generic     PHP                 Disallow short open tag                    1
Zend        Files               Closing tag                                1
--------------------------------------------------------------------------------
A TOTAL OF 305 SNIFF VIOLATION(S) WERE FOUND IN 10 SOURCE(S)
--------------------------------------------------------------------------------

As you can see from this report, although we are using the Zend standard, it consists of individual rules from multiple standards.

In the next part of this series I will cover how to write your own standard, by selecting rules from existing standards.

This started as a quick blog post on my way home. I was drunk, and shouldn’t have been blogging. I’d been to the leaving do of two of my great colleagues at Yahoo!

It ended up way too long,  so I have split it up into sections and will post as a series.

This is a rough transcript of a lightning talk I gave during a team meeting at Yahoo! completely off the cuff, but I am in the process of writing this up as a Yahoo! Tech Talk, and also, as this is not internally sensitive, like most of the stuff I’ve been working on for the last two years, I’ll see if it can be release on Yahoo Developers Network.

What is CodeSniffer?

CodeSniffer is almost a SCA tool. It allows a set of rules or a Standard to be applied to source code.

These rules can be used to detect common programming errors or Anti Patterns, it can also be used to define a set of Coding Standards  for your project.

It is down to your project to come up with some Coding Standards or apply a pre-existing set of standards for your team to adhere to.

CodeSniffer comes with a set of coding standards already defined that are regularly used by other teams.

These are:

• MySource
• PEAR
• PHPCS
• Squiz
• Zend

Analysing your code using one or more of these standards will highlight how the code you have provided stacks up against the project’s coding standard.

How to install CodeSniffer

$ sudo pear install PHP_CodeSniffer

This will download and install the CodeSniffer utility from the PEAR repository.

How to run CodeSniffer

Simply run:

$ phpcs --standard=<standard> <path to file or directory>

You will be shown a list any errors or warnings in your code.

CodeSniffer will also exit with a non-zero status code. This can be useful if you are using a Makefile to test your code or some build tool like Phing, or if your CodeSniffer rules are being run as part of a Continuous Integration system.

In the next post I will run through some of the standards and reports.