CodeSniffer

Moodle 2.0

Overview

Scope

This document describes the CodeSniffing/Code checker tools their purpose and usage.

Function

The function of the CodeSniffer tool is to analyse PHP5 (only) code, apply a set of rules that match the Moodle Coding Style, and output a report showing which parts of the code do not conform to this style.

Usage

Simple example

The script is located in lib/pear/PHP and is called runsniffer. To check the syntax of a given file (e.g. index.php), run:

lib/pear/PHP/runsniffer index.php

You will get a report that looks like this:

 --------------------------------------------------------------------------------
 FOUND 139 ERROR(S) AND 24 WARNING(S) AFFECTING 130 LINE(S)
 --------------------------------------------------------------------------------
    1 | WARNING | $Id$ tag is no longer required, please remove.
   28 | ERROR   | line indented incorrectly; expected 0 spaces, found 4
   50 | ERROR   | line indented incorrectly; expected 0 spaces, found 4
   50 | ERROR   | A cast statement must be followed by a single space
   55 | ERROR   | line indented incorrectly; expected 0 spaces, found 4
 ....

The first column shows the line at which the ERROR or WARNING was found. The CodeSniffer uses a set of rules which are still being defined, so that what is currently defined as ERROR or WARNING is likely to change in the near future.

You should fix all ERRORs, but may safely ignore the WARNINGs. Fixing warnings will help your code be even more readable and consistent with other code that follow this standard.

Advanced Usage

Ignoring warnings

You can run the CodeSniffer with the -n flag to ignore warnings:

lib/pear/PHP/runsniffer -n index.php

Resulting output:

 --------------------------------------------------------------------------------
 FOUND 139 ERROR(S) AFFECTING 125 LINE(S)
 --------------------------------------------------------------------------------
   28 | ERROR | line indented incorrectly; expected 0 spaces, found 4
   50 | ERROR | line indented incorrectly; expected 0 spaces, found 4
 ...

Recursive analysis

If you give the name of a folder instead of a file, it will search, analyse and report on all PHP files found in this folder and all its subfolders. This will produce a full report for each PHP file. Since this is likely to be too much information, you may want to print only a summary report, by using the following syntax (search the files/ folder as an example):

lib/pear/PHP/runsniffer --report=summary files

Report:

 PHP CODE SNIFFER REPORT SUMMARY
 --------------------------------------------------------------------------------
 FILE                                                            ERRORS  WARNINGS
 --------------------------------------------------------------------------------
 /web/htdocs/moodle_blog2/files/index.php                        11      58
 /web/htdocs/moodle_blog2/files/draftfiles.php                   6       22
 --------------------------------------------------------------------------------
 A TOTAL OF 17 ERROR(S) AND 80 WARNING(S) WERE FOUND IN 2 FILE(S)
 --------------------------------------------------------------------------------

You can also use the -n flag to ignore warnings.

Several files in one folder

If you want to search all files under a folder, but not recurse through the subfolders, you can use the -l flag (local files only):

lib/pear/PHP/runsniffer --report=summary -l grade

 PHP CODE SNIFFER REPORT SUMMARY
 --------------------------------------------------------------------------------
 FILE                                                            ERRORS  WARNINGS
 --------------------------------------------------------------------------------
 /web/htdocs/moodle_blog2/grade/index.php                        0       2
 /web/htdocs/moodle_blog2/grade/lib.php                          6       210
 /web/htdocs/moodle_blog2/grade/querylib.php                     5       39
 --------------------------------------------------------------------------------
 A TOTAL OF 11 ERROR(S) AND 251 WARNING(S) WERE FOUND IN 3 FILE(S)
 --------------------------------------------------------------------------------

You can pass as many files and folders to the script as you want, the analysis and flags will apply to all of them.

Special rules

When recursing through folders, the CodeSniffer script looks for a file called thirdpartylibs.xml. Currently there is only one, found under lib/. It lists directories and files which are meant to stay 'as-is' in Moodle, in order to ensure minimum hassle when upgrading these libraries. You can use this file as a template to create your own list of exceptions.

Other report formats

CodeSniffer can export its reports in the following formats:

1. full: default, shown first above
2. summary: also shown above
3. xml: Simple XML format
4. csv: Comma-separated list
5. checkstyle: XML format intended for use with CruiseControl

See also

1. Coding
2. Coding style