Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

CodeSniffer: Difference between revisions

From MoodleDocs
m (Protected "CodeSniffer": Developer Docs Migration ([Edit=Allow only administrators] (indefinite)))
 
(24 intermediate revisions by 9 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 20: Line 22:
/question/type/shortanswer
/question/type/shortanswer


You would then be presentedwith 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 probably not include Moodle. To install the moodle standards copy the moodle folder from local\codechecker into your standards directory which for me was under
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
[[Image:codesniffer.jpg]]


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:


<code>
<syntaxhighlight lang="php">
lib/pear/PHP/runsniffer index.php
lib/pear/PHP/runsniffer index.php
</code>
</syntaxhighlight>


You will get a report that looks like this:
You will get a report that looks like this:


<code>
<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 91: Line 179:
     55 | ERROR  | line indented incorrectly; expected 0 spaces, found 4
     55 | ERROR  | line indented incorrectly; expected 0 spaces, found 4
   ....
   ....
</code>
</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 101: 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:


<code>
<syntaxhighlight lang="php">
lib/pear/PHP/runsniffer -n index.php
lib/pear/PHP/runsniffer -n index.php
</code>
</syntaxhighlight>


Resulting output:
Resulting output:
<code>
<syntaxhighlight lang="php">
   --------------------------------------------------------------------------------
   --------------------------------------------------------------------------------
   FOUND 139 ERROR(S) AFFECTING 125 LINE(S)
   FOUND 139 ERROR(S) AFFECTING 125 LINE(S)
Line 113: Line 201:
     50 | ERROR | line indented incorrectly; expected 0 spaces, found 4
     50 | ERROR | line indented incorrectly; expected 0 spaces, found 4
   ...
   ...
</code>
</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):


<code>
<syntaxhighlight lang="php">
lib/pear/PHP/runsniffer --report=summary files
lib/pear/PHP/runsniffer --report=summary files
</code>
</syntaxhighlight>


Report:
Report:
<code>
<syntaxhighlight lang="php">
   PHP CODE SNIFFER REPORT SUMMARY
   PHP CODE SNIFFER REPORT SUMMARY
   --------------------------------------------------------------------------------
   --------------------------------------------------------------------------------
Line 133: 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)
   --------------------------------------------------------------------------------
   --------------------------------------------------------------------------------
</code>
</syntaxhighlight>


You can also use the -n flag to ignore warnings.
You can also use the -n flag to ignore warnings.
Line 140: 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):


<code>
<syntaxhighlight lang="php">
lib/pear/PHP/runsniffer --report=summary -l grade
lib/pear/PHP/runsniffer --report=summary -l grade


Line 153: 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)
   --------------------------------------------------------------------------------
   --------------------------------------------------------------------------------
</code>
</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

codesniffer.jpg

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