CodeSniffer
Moodle 2.0
Overview
Scope
This document describes the CodeSniffer tool added in Moodle 2.0, its 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:
- full: default, shown first above
- summary: also shown above
- xml: Simple XML format
- csv: Comma-separated list
- checkstyle: XML format intended for use with CruiseControl
