CodeSniffer: Difference between revisions
Marcus Green (talk | contribs) No edit summary |
Dev Docs Bot (talk | contribs) m (Protected "CodeSniffer": Developer Docs Migration ([Edit=Allow only administrators] (indefinite))) |
||
(23 intermediate revisions by 8 users not shown) | |||
Line 1: | Line 1: | ||
{{Template:Migrated|newDocId=/general/development/tools/phpcs}} | |||
{{Moodle 2.0}} | {{Moodle 2.0}} | ||
Line 10: | Line 11: | ||
==Usage== | ==Usage== | ||
===Using codechecker=== | ===Using codechecker=== | ||
Line 21: | Line 23: | ||
You would then be presented with a list of the count of files processed and any warnings or errors. | 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: | |||
<syntaxhighlight lang="php"> | |||
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: | |||
<syntaxhighlight lang="php"> | |||
phpcs --config-set default_standard moodle | |||
</syntaxhighlight> | |||
'''Install using composer''' | |||
1. Run the following in your terminal from your moodle folder: | |||
<syntaxhighlight lang="php"> | |||
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 | |||
<syntaxhighlight lang="php"> | |||
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: | |||
<syntaxhighlight lang="php"> | |||
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: | |||
<syntaxhighlight lang="php"> | |||
phpcs --config-set default_standard moodle | |||
</syntaxhighlight> | |||
===Codechecker output=== | ===Codechecker output=== | ||
Line 61: | Line 129: | ||
Once installed you can check it within Netbeans by going to | Once installed you can check it within Netbeans by going to | ||
Tools/Options/PHP and click on the codesniffer tab. | 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 | There is an option for the codesniffer script. On my windows xampp install this needs to point to | ||
Line 66: | Line 136: | ||
C:\xampp\php\phpcs.bat | C:\xampp\php\phpcs.bat | ||
Underneath this should be a list of some of the coding standards available, but by default this will | 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 | php\PEAR\PHP\CodeSniffer\Standards | ||
Line 73: | Line 143: | ||
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". | 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=== | ===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: | 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: | ||
< | <syntaxhighlight lang="php"> | ||
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: | ||
< | <syntaxhighlight lang="php"> | ||
-------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ||
FOUND 139 ERROR(S) AND 24 WARNING(S) AFFECTING 130 LINE(S) | FOUND 139 ERROR(S) AND 24 WARNING(S) AFFECTING 130 LINE(S) | ||
Line 93: | Line 179: | ||
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 103: | Line 189: | ||
You can run the CodeSniffer with the -n flag to ignore warnings: | You can run the CodeSniffer with the -n flag to ignore warnings: | ||
< | <syntaxhighlight lang="php"> | ||
lib/pear/PHP/runsniffer -n index.php | lib/pear/PHP/runsniffer -n index.php | ||
</ | </syntaxhighlight> | ||
Resulting output: | Resulting output: | ||
< | <syntaxhighlight lang="php"> | ||
-------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ||
FOUND 139 ERROR(S) AFFECTING 125 LINE(S) | FOUND 139 ERROR(S) AFFECTING 125 LINE(S) | ||
Line 115: | Line 201: | ||
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==== | ||
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): | 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): | ||
< | <syntaxhighlight lang="php"> | ||
lib/pear/PHP/runsniffer --report=summary files | lib/pear/PHP/runsniffer --report=summary files | ||
</ | </syntaxhighlight> | ||
Report: | Report: | ||
< | <syntaxhighlight lang="php"> | ||
PHP CODE SNIFFER REPORT SUMMARY | PHP CODE SNIFFER REPORT SUMMARY | ||
-------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ||
Line 135: | Line 221: | ||
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 142: | Line 228: | ||
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): | 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): | ||
< | <syntaxhighlight lang="php"> | ||
lib/pear/PHP/runsniffer --report=summary -l grade | lib/pear/PHP/runsniffer --report=summary -l grade | ||
Line 155: | Line 241: | ||
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. | ||
===Special rules=== | ===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. | |||
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=== | ===Other report formats=== |
Latest revision as of 07:26, 6 May 2022
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