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:

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