Merge pull request #742 from andrewnicols/phpcs_updates

Updates for phpcs documentation

Author: ilyatregubov

general/development/tools/phpcs.md

@@ -9,22 +9,25 @@ sidebar_position: 1
 
 import { Since } from '@site/src/components';
 
-## Overview
+[PHPCodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) is a tool used to analyse PHP code using a set of rules. In many cases these rules can be used to automatically fix the errors they identify.
 
-This document describes the various code sniffing tools that Moodle recommends, their purpose, and their usage.
+Moodle has two sets of published rule-sets intended to meet the [Moodle Coding Style](../policies/codingstyle/index.md), and identify any parts of the code do not conform to this style. These are:
 
-[PHPCodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) is a tool used to analyse PHP code using a set of rules. In many cases these rules can be used to automatically fix the errors they identify.
+- `moodle` - The standard ruleset which meets all variants of the coding style
+- `moodle-extra` - The extended standard which includes recommended best practices
 
-Moodle has published a ruleset intended to meet the [Moodle Coding Style](../policies/codingstyle/index.md), and identify any parts of the code do not conform to this style.
+We recommend use of the `moodle-extra` standard, particularly when writing new code.
 
 ## Installation
 
-It is recommend that both the phpcs scripts, and the Moodle ruleset, are installed globally using Composer:
+The recommended method of installation is via the global composer command:
 
 ```console
 composer global require moodlehq/moodle-cs
 ```
 
+This ensures that you have a single copy of the standard used for all code.
+
 ### Configuration
 
 <Since versions={["4.1.0", "4.0.1", "3.11.7"]} issueNumber="MDL-74511" />
@@ -33,9 +36,23 @@ A PHPCS configuration is included in the Moodle codebase and ensures that the co
 
 This can be further extended by generating an additional configuration to ignore all third-party libraries using the `grunt ignorefiles` command. See [grunt](./nodejs.md#grunt) for further information on using Grunt.
 
-#### Community plugins, and older Moodle versions
+If you would like to make use of the `moodle-extra` standard then you should create a `.phpcs.xml` file with the following content:
 
-If you are developing your own plugin outside of the main Moodle directory, or you are working with an older version of Moodle, the easiest way to configure phpcs to use the Moodle ruleset is by creating a local `phpcs.xml.dist` configuration at the root directory of your repository with the following content:
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ruleset name="MoodleCore">
+  <rule ref="./phpcs.xml"/>
+  <rule ref="moodle-extra"/>
+</ruleset>
+```
+
+This will extend the standard configuration, and apply the extra standard on top of it.
+
+#### Moodle 3.10 and earlier
+
+The easiest way to have PHP CodeSniffer pick up your preferred style is via a local configuration file.
+
+You can create a file named `.phpcs.xml` with the following contents:
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
@@ -44,48 +61,42 @@ If you are developing your own plugin outside of the main Moodle directory, or y
 </ruleset>
 ```
 
-If you do not wish to include this file in your repository, or you are using an older version of Moodle, then you should add this to your local gitignore files. On a Unix-like system this can be achieved with:
+If you wish to use the `moodle-extra` coding style, then you can use the following content:
 
-```console
-echo phpcs.xml.dist >> .git/info/exclude
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ruleset name="MoodleCore">
+  <rule ref="moodle-extra"/>
+</ruleset>
 ```
 
 :::info
 
-The `.git/info/exclude` file is a per-repository version of the `.gitignore` file. Whilst `.gitignore` is tracked within the Moodle codebase and a version is shipped with Moodle, the `.git/info/exclude` file is local to your git clone.
-
-See the [gitignore](https://git-scm.com/docs/gitignore) documentation for more information on the gitignore feature.
+Third-party library code will not be ignored with these versions of Moodle.
 
 :::
 
-#### System-side default standard
-
-Although not recommended, you can configure the Moodle ruleset as the system-wide default for phpcs:
-
-```php
-phpcs --config-set default_standard moodle
-```
-
-:::important Not recommended
+:::tip Ignoring the file with Git
 
-This approach is **not recommended** and is only preserved for reference.
+We recommend configuring your code checkout to ignore the `.phpcs.xml` file by adding a local ignore record to `.git/info/exclude`
 
 :::
 
-## Moodle plugin
-
-Moodle includes a copy of the PHPCodeSniffer package, and the Moodle ruleset, as part of the [`moodle-local_codechecker`](https://github.com/moodlehq/moodle-local_codechecker) Moodle plugin. This makes the code checker available via a web-based interface for checking the syntax of a given file or folder.
+#### Community plugins, and older Moodle versions
 
-One way to install this plugin is using `git clone`:
+If you are developing your own plugin outside of the main Moodle directory, or you are working with an older version of Moodle, the easiest way to configure phpcs to use the Moodle ruleset is by creating a local `phpcs.xml.dist` configuration at the root directory of your repository with the following content:
 
-```console
-git clone https://github.com/moodlehq/moodle-local_codechecker.git local/codechecker
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ruleset name="MoodleCore">
+  <rule ref="moodle"/>
+</ruleset>
 ```
 
-It is recommended that you add the plugin to your _local_ git ignore:
+If you do not wish to include this file in your repository, or you are using an older version of Moodle, then you should add this to your local gitignore files. On a Unix-like system this can be achieved with:
 
 ```console
-echo local/codechecker >> .git/info/exclude
+echo phpcs.xml.dist >> .git/info/exclude
 ```
 
 :::info
@@ -96,23 +107,19 @@ See the [gitignore](https://git-scm.com/docs/gitignore) documentation for more i
 
 :::
 
-:::note
-
-If you are not installing the moodle ruleset globally, and are instead using the [`local_codechecker`](https://github.com/moodlehq/moodle-local_codechecker) plugin, then you _must_ also use the version of phpcs distributed in the plugin.
-
-This is located at `local/codechecker/phpcs/bin/phpcs`.
+#### System-side default standard
 
-:::
+Although not recommended, you can configure the Moodle ruleset as the system-wide default for phpcs:
 
-Once installed a new codechecker option will appear in the Site administration -> Development page.
+```php
+phpcs --config-set default_standard moodle
+```
 
-This page allows for the code in a specified directory to be checked, for example if you wanted to check the code for the `shortanswer` question type you would enter
+:::important Not recommended
 
-```
-/question/type/shortanswer
-```
+This approach is **not recommended** and is only preserved for reference.
 
-You would then be presented with a list of the count of files processed and any warnings or errors.
+:::
 
 ## Editor integrations