[docs] Mention new moodle-extra style

Author: andrewnicols

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,6 +36,52 @@ 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.
 
+If you would like to make use of the `moodle-extra` standard then you should create a `.phpcs.xml` file 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"?>
+<ruleset name="MoodleCore">
+  <rule ref="moodle"/>
+</ruleset>
+```
+
+If you wish to use the `moodle-extra` coding style, then you can use the following content:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ruleset name="MoodleCore">
+  <rule ref="moodle-extra"/>
+</ruleset>
+```
+
+:::info
+
+Third-party library code will not be ignored with these versions of Moodle.
+
+:::
+
+:::tip Ignoring the file with Git
+
+We recommend configuring your code checkout to ignore the `.phpcs.xml` file by adding a local ignore record to `.git/info/exclude`
+
+:::
+
 #### Community plugins, and older Moodle versions
 
 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: