CodeSniffer: Difference between revisions
Mark Sharp (talk | contribs) |
David Mudrak (talk | contribs) m (Text replacement - "</code>" to "</syntaxhighlight>") |
||
Line 55: | Line 55: | ||
<code> | <code> | ||
The installed coding standards are MySource, PHPCompatibility, Squiz, PSR2, moodle, PEAR, PSR1, PSR12 and Zend | The installed coding standards are MySource, PHPCompatibility, Squiz, PSR2, moodle, PEAR, PSR1, PSR12 and Zend | ||
</ | </syntaxhighlight> | ||
5. Optionally, you can set the default standard in a configuration file: | 5. Optionally, you can set the default standard in a configuration file: | ||
<code> | <code> | ||
phpcs --config-set default_standard moodle | phpcs --config-set default_standard moodle | ||
</ | </syntaxhighlight> | ||
'''Install using composer''' | '''Install using composer''' | ||
Line 67: | Line 67: | ||
<code> | <code> | ||
composer global require "squizlabs/php_codesniffer=3.*" | composer global require "squizlabs/php_codesniffer=3.*" | ||
</ | </syntaxhighlight> | ||
2. Download the standard: PHPCompatibility and moodle directories from https://github.com/moodlehq/moodle-local_codechecker | 2. Download the standard: PHPCompatibility and moodle directories from https://github.com/moodlehq/moodle-local_codechecker | ||
Line 77: | Line 77: | ||
<code> | <code> | ||
phpcs --config-set installed_paths /path/to/moodle-local_codechecker # adds moodle's standard to phpcs | phpcs --config-set installed_paths /path/to/moodle-local_codechecker # adds moodle's standard to phpcs | ||
</ | </syntaxhighlight> | ||
4. If they are installed properly, moodle and PHPCompatibility will show up in the output of `phpcs -i`. Here is a typical example: | 4. If they are installed properly, moodle and PHPCompatibility will show up in the output of `phpcs -i`. Here is a typical example: | ||
<code> | <code> | ||
The installed coding standards are MySource, PHPCompatibility, Squiz, PSR2, moodle, PEAR, PSR1, PSR12 and Zend | The installed coding standards are MySource, PHPCompatibility, Squiz, PSR2, moodle, PEAR, PSR1, PSR12 and Zend | ||
</ | </syntaxhighlight> | ||
5. Optionally, you can set the default standard in a configuration file: | 5. Optionally, you can set the default standard in a configuration file: | ||
<code> | <code> | ||
phpcs --config-set default_standard moodle | phpcs --config-set default_standard moodle | ||
</ | </syntaxhighlight> | ||
===Codechecker output=== | ===Codechecker output=== | ||
Line 164: | Line 164: | ||
<code> | <code> | ||
lib/pear/PHP/runsniffer index.php | lib/pear/PHP/runsniffer index.php | ||
</ | </syntaxhighlight> | ||
You will get a report that looks like this: | You will get a report that looks like this: | ||
Line 178: | Line 178: | ||
55 | ERROR | line indented incorrectly; expected 0 spaces, found 4 | 55 | ERROR | line indented incorrectly; expected 0 spaces, found 4 | ||
.... | .... | ||
</ | </syntaxhighlight> | ||
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. | 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. | ||
Line 190: | Line 190: | ||
<code> | <code> | ||
lib/pear/PHP/runsniffer -n index.php | lib/pear/PHP/runsniffer -n index.php | ||
</ | </syntaxhighlight> | ||
Resulting output: | Resulting output: | ||
Line 200: | Line 200: | ||
50 | ERROR | line indented incorrectly; expected 0 spaces, found 4 | 50 | ERROR | line indented incorrectly; expected 0 spaces, found 4 | ||
... | ... | ||
</ | </syntaxhighlight> | ||
====Recursive analysis==== | ====Recursive analysis==== | ||
Line 207: | Line 207: | ||
<code> | <code> | ||
lib/pear/PHP/runsniffer --report=summary files | lib/pear/PHP/runsniffer --report=summary files | ||
</ | </syntaxhighlight> | ||
Report: | Report: | ||
Line 220: | Line 220: | ||
A TOTAL OF 17 ERROR(S) AND 80 WARNING(S) WERE FOUND IN 2 FILE(S) | A TOTAL OF 17 ERROR(S) AND 80 WARNING(S) WERE FOUND IN 2 FILE(S) | ||
-------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ||
</ | </syntaxhighlight> | ||
You can also use the -n flag to ignore warnings. | You can also use the -n flag to ignore warnings. | ||
Line 240: | Line 240: | ||
A TOTAL OF 11 ERROR(S) AND 251 WARNING(S) WERE FOUND IN 3 FILE(S) | A TOTAL OF 11 ERROR(S) AND 251 WARNING(S) WERE FOUND IN 3 FILE(S) | ||
-------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ||
</ | </syntaxhighlight> | ||
You can pass as many files and folders to the script as you want, the analysis and flags will apply to all of them. | You can pass as many files and folders to the script as you want, the analysis and flags will apply to all of them. |
Revision as of 13:02, 14 July 2021
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
</syntaxhighlight>
5. Optionally, you can set the default standard in a configuration file:
phpcs --config-set default_standard moodle
</syntaxhighlight>
Install using composer
1. Run the following in your terminal from your moodle folder:
composer global require "squizlabs/php_codesniffer=3.*"
</syntaxhighlight>
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
</syntaxhighlight>
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
</syntaxhighlight>
5. Optionally, you can set the default standard in a configuration file:
phpcs --config-set default_standard moodle
</syntaxhighlight>
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
</syntaxhighlight>
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
....
</syntaxhighlight>
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
</syntaxhighlight>
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
...
</syntaxhighlight>
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
</syntaxhighlight>
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)
--------------------------------------------------------------------------------
</syntaxhighlight>
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)
--------------------------------------------------------------------------------
</syntaxhighlight>
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
See also