CodeSniffer
| Important:
This content of this page has been updated and migrated to the new Moodle Developer Resources. The information contained on the page should no longer be seen up-to-date. Why not view this page on the new site and help us to migrate more content to the new site! |
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
Using codechecker
codechecker is a local plugin that creates a web based interface for checking the syntax of a given file. It can be found at https://github.com/moodlehq/moodle-local_codechecker
Once installed a new codechecker option will appear in site administration\development page.
This page allows for the code in a specified directory to be checked, e.g. if you wanted to check the code for the shortanswer question type you would enter /question/type/shortanswer
You would then be presented with a list of the count of files processed and any warnings or errors.
Installing codechecker
To install using git, type this command in the root of your Moodle install
git clone git://github.com/moodlehq/moodle-local_codechecker.git local/codechecker
Then edit .gitignore in your development folder eg:
gedit /var/www/moodle/.gitignore
And add /local/codechecker/ - including the slash at the end
Alternatively, download the zip from
https://github.com/moodlehq/moodle-local_codechecker/zipball/master
unzip it into the local folder, and then rename the new folder to codechecker.
Installing PHP CS
Using pear installer
1. Install the Pear package for PHP CS, pear install PHP_CodeSniffer
2. Download the standard: PHPCompatibility and moodle directories from https://github.com/moodlehq/moodle-local_codechecker
3. Copy the previous directories to the PHP CS standard path:
- in Mac with Macports is /opt/local/lib/php/PHP/CodeSniffer/Standards/
- In Mac with Homebrew is /usr/local/share/pear\@7.0/PHP/CodeSniffer/Standards/
- in Linux is /usr/share/php/PHP/CodeSniffer/Standards/ or /usr/share/php/PHP/CodeSniffer/src/Standards
4. If they are installed properly, moodle and PHPCompatibility will show up in the output of `phpcs -i`. Here is a typical example:
The installed coding standards are MySource, PHPCompatibility, Squiz, PSR2, moodle, PEAR, PSR1, PSR12 and Zend
5. Optionally, you can set the default standard in a configuration file:
phpcs --config-set default_standard moodle
Install using composer
1. Run the following in your terminal from your moodle folder:
composer global require "squizlabs/php_codesniffer=3.*"
2. Download the standard: PHPCompatibility and moodle directories from https://github.com/moodlehq/moodle-local_codechecker to an accessible location on your computer - it doesn't have to be your project folder.
Note: "blackboard-open-source/moodle-coding-standard" is no longer being maintained.
3. Tell phpcs about where to find the Moodle code checker
phpcs --config-set installed_paths /path/to/moodle-local_codechecker # adds moodle's standard to phpcs
4. If they are installed properly, moodle and PHPCompatibility will show up in the output of `phpcs -i`. Here is a typical example:
The installed coding standards are MySource, PHPCompatibility, Squiz, PSR2, moodle, PEAR, PSR1, PSR12 and Zend
5. Optionally, you can set the default standard in a configuration file:
phpcs --config-set default_standard moodle
Codechecker output
The output is similar to the following
Files found: 21
question\type\calculated\backup\moodle1\lib.php - 1 error(s) and 10 warning(s) then a list of all files checked with a count of errors and warnings..followed by a summary Total: 31 error(s) and 262 warning(s)
Then a list describing the exact issue in each file
question\type\calculated\backup\moodle1\lib.php 2: The opening <?php tag must be followed by exactly one newline. ········//·convert·and·write·the·answers·first 50: Inline comments must start with a capital letter, digit or 3-dots sequence etc etc You can then edit the files to attempt to remove each issue.
IDE plugin alternatives
Using the web based interface means switching between the browser and the editing environment. You may find it easier to use a plugin that allows you to check your code against the standards as you go along.
For Eclipse users http://www.phpsrc.org/
For Netbeans users
Make sure you have the PEAR php Codesniffer code installed, you can find instructions at http://pear.php.net/package/PHP_CodeSniffer/download/All
Then install the netbeans plugin which can be found at
https://github.com/beberlei/netbeans-php-enhancements/downloads
Once installed you can check it within Netbeans by going to Tools/Options/PHP and click on the codesniffer tab.
Windows set up
There is an option for the codesniffer script. On my windows xampp install this needs to point to
C:\xampp\php\phpcs.bat
Underneath this should be a list of some of the coding standards available, but by default this will not include Moodle. To install the moodle standard, copy the"moodle" and "phpcompatibility" folders from local\codechecker into your standards directory which for me was under
php\PEAR\PHP\CodeSniffer\Standards
Now when you restart your Netbeans you should see a new moodle coding standard. Right clicking on a file name should present you with a new option of "Show Code Standard Violations".
Linux set up
After installing codesniffer and codechecker, copy the moodle and phpcompatibility standard folders from (assuming you have the code in /local/codechecker)
/var/www/moodle/local/codechecker/
to
/usr/share/pear/PHP/CodeSniffer/Standards/
There is an option to set the default standard in a configuration file:
phpcs --config-set default_standard moodle
Then restart Netbeans and it should now work. You can also switch between coding standards.
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 core, 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.
For using the thirdpartylibs.xml in your plugins, please see Plugin files#thirdpartylibs.xml.
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
