Add a new moodle-extra coding style

Author: andrewnicols

CHANGELOG.md

@@ -7,6 +7,10 @@ The format of this change log follows the advice given at [Keep a CHANGELOG](htt
 
 ## [Unreleased]
 
+### Added
+
+- A new moodle-extra coding standard which moves towards a more PSR-12 compliant coding style
+
 ## [v3.3.5] - 2023-08-28
 ### Changed
 - Update composer dependencies to current versions, notably PHPCompatibility (0a17f9ed).

README.md

@@ -16,81 +16,72 @@
 
 ## Information
 
-This repository contains the Moodle Coding Style configuration.
+This repository contains the Moodle Coding Style configurations, written as [PHP CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) rulesets.
 
-Currently this only includes the configuration for PHP Coding style, but this
-may be extended to include custom rules for JavaScript, and any other supported
-languages or syntaxes.
+Two coding styles are included:
 
+- `moodle` - the main ruleset for the [Moodle Coding Style](https://moodledev.io/general/development/policies/codingstyle)
+- `moodle-extra` - extended ruleset which includes recommended best practices
+  - extends the main `moodle` ruleset
+
+Currently this only includes the configuration for PHP Coding style, but this may be extended to include custom rules for JavaScript, and any other supported languages or syntaxes.
 
 ## Installation
 
-### Using Composer
+### Using Composer (recommended)
 
-You can include these coding style rules using Composer to make them available
-globally across your system.
+You can install these coding style rules using Composer to make them available globally across your system.
 
-This will install the correct version of phpcs, with the Moodle rules, and their
-dependencies.
+This will install the correct version of phpcs, with the Moodle rules, and their dependencies.
 
-```
+```shell
 composer global require moodlehq/moodle-cs
 ```
 
-### As a part of moodle-local_codechecker
-
-This plugin is included as part of the [moodle-local_codechecker
-plugin](https://github.com/moodlehq/moodle-local_codechecker).
-
-
 ## Configuration
 
-You can set the Moodle standard as the system default:
-```
-phpcs --config-set default_standard moodle
-```
-
-This will inform most IDEs automatically.
-Alternatively you can configuration your IDE to use phpcs with the Moodle
-ruleset as required.
-
+Typically configuration is not required. Recent versions of Moodle (3.11 onwards) include a configuration file for the PHP CodeSniffer, which will set the standard when run within a Moodle directory.
 
-### IDE Integration
+Additional configuration can be generated automatically to have PHP CodeSniffer ignore any third-party library code. This can be generated by running:
 
-#### PhpStorm
-
-1. Open PhpStorm preferences
-2. Go to Inspections > PHP > PHP Code Sniffer Validation
-3. In the 'coding standard' dropdown, select 'moodle'
+```shell
+npx grunt ignorefiles
+```
 
-#### Sublime Text
+### Using the `moodle-extra` coding style
 
-Find documentation [here](https://docs.moodle.org/dev/Setting_up_Sublime2#Sublime_PHP_CS).
+The recommended way of configuring PHP CodeSniffer to use the `moodle-extra` coding style is to provide an additional configuration file.
 
-1. Go in your Sublime Text to Preferences -> Package Control -> Package Control: Install Package
-2. Write 'phpcs' in the search field, if you see Phpcs and SublimeLinter-phpcs, click on them to install them.
-3. If not, check if they are already installed Preferences -> Package Control -> Package Control: Remove Package.
-4. To set your codecheck to moodle standards go to Preferences -> Package Settings -> PHP Code Sniffer -> Settings-User and write:
+For Moodle 3.11 onwards you can create a file named `.phpcs.xml` with the following contents:
 
-        { "phpcs_additional_args": {
-                "--standard": "moodle",
-                "-n": "
-            },
-        }
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ruleset name="MoodleCore">
+  <rule ref="./phpcs.xml"/>
+  <rule ref="moodle-extra"/>
+</ruleset>
+```
 
-5. If you don’t have the auto-save plugin turned on, YOU’RE DONE!
-6. If you have the auto-save plugin turned on, because the codecheck gets triggered on save, the quick panel will keep popping making it impossible to type.
-   To stop quick panel from showing go to Settings-User file and add:
+This will load the `phpcs.xml` file (generated by `npx grunt ignorefiles`), and apply the `moodle-extra` configuration on top.
 
-        "phpcs_show_quick_panel": false,
+### Moodle 3.10 and earlier
 
-   The line with the error will still get marked and if you’ll click on it you’ll see the error text in the status bar.
+The easiset way to have PHP CodeSniffer pick up your preferred style, you can create a file named `phpcs.xml` with the following contents:
 
-#### VSCode
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ruleset name="MoodleCore">
+  <rule ref="moodle"/>
+</ruleset>
+```
 
-Find documentation [here](https://docs.moodle.org/dev/Setting_up_VSCode#PHP_CS).
+If you wish to use the `moodle-extra` coding style, then you can use the following content:
 
-1. Install [PHPSniffer](https://marketplace.visualstudio.com/items?itemName=wongjn.php-sniffer).
-2. Open VSCode settings.json and add the following setting to define standard PHP CS (if you haven't set it as default in your system):
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ruleset name="MoodleCore">
+  <rule ref="moodle-extra"/>
+</ruleset>
+```
 
-        "phpSniffer.standard": "moodle",
+Note: Third-party library code will not be ignored with these versions of Moodle.

composer.json

@@ -12,11 +12,16 @@
         {
             "name": "Andrew Lyons",
             "email": "[email protected]"
+        },
+        {
+            "name": "Eloy Lafuente",
+            "email": "[email protected]"
         }
     ],
     "require": {
         "dealerdirect/phpcodesniffer-composer-installer": "^1.0.0",
         "squizlabs/php_codesniffer": "^3.7.2",
+        "phpcsstandards/phpcsextra": "^1.1.0",
         "phpcompatibility/php-compatibility": "dev-develop#0a17f9ed"
     },
     "config": {

moodle-extra/ruleset.xml

@@ -0,0 +1,82 @@
+<?xml version="1.0"?>
+<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/squizlabs/PHP_CodeSniffer/master/phpcs.xsd"
+    name="moodle-strict"
+    namespace="MoodleHQ\MoodleCS\MoodleExtra">
+
+    <description>Best Practices for Moodle development beyond the core Coding Standards</description>
+
+    <!-- Extend the standard Moodle coding style -->
+    <rule ref="moodle"/>
+
+    <!-- Include the PSR-12 ruleset with relevant Moodle exclusions -->
+    <rule ref="PSR12">
+
+        <!-- Moodle has a header manager and places its copyright on the first line after the opening tag -->
+        <exclude name="PSR12.Files.FileHeader.SpacingAfterBlock"/>
+
+        <!-- Moodle already defines its own line length, so remove this from the PSR-12 standard -->
+        <exclude name="Generic.Files.LineLength.TooLong"/>
+
+        <!-- Moodle has its own custom sniff for side effects  -->
+        <exclude name="PSR1.Files.SideEffects.FoundWithSymbols"/>
+
+        <!-- Moodle does not support camel case at all -->
+        <exclude name="PSR1.Methods.CamelCapsMethodName.NotCamelCaps"/>
+
+        <!-- Moodle contains a lot of code which pre-dates PHP 7.1 and did not support constant visibility -->
+        <exclude name="PSR12.Properties.ConstantVisibility.NotFound"/>
+
+        <!-- Moodle does not place the opening brace on a new line -->
+        <exclude name="PSR2.Classes.ClassDeclaration.OpenBraceNewLine"/>
+
+        <!-- Moodle allows use of else if-->
+        <exclude name="PSR2.ControlStructures.ElseIfDeclaration.NotAllowed"/>
+
+        <!-- Moodle casing rules do not allow camel case at all -->
+        <exclude name="Squiz.Classes.ValidClassName.NotCamelCaps"/>
+
+        <!-- Moodle casing currently places the brace in the same line -->
+        <exclude name="Squiz.Functions.MultiLineFunctionDeclaration.BraceOnSameLine"/>
+    </rule>
+
+    <!-- Detect duplicate array keys -->
+    <rule ref="Universal.Arrays.DuplicateArrayKey"/>
+
+    <!-- Require a comma after the last element in a multi-line array, but prevent in a single-line array definition -->
+    <rule ref="NormalizedArrays.Arrays.CommaAfterLast"/>
+
+    <!-- Disallow use of list() instead of [] -->
+    <rule ref="Universal.Lists.DisallowLongListSyntax"/>
+
+    <!-- Enusre that ::class is lower-cased -->
+    <rule ref="Universal.Constants.LowercaseClassResolutionKeyword"/>
+
+    <!-- Require a consistent modifier keyword order for OO constant declarations -->
+    <rule ref="Universal.Constants.ModifierKeywordOrder"/>
+
+    <!-- Enforce that the names used in a class/enum "implements" statement or an interface "extends" statement are listed in alphabetic order -->
+    <rule ref="Universal.OOStructures.AlphabeticExtendsImplements"/>
+
+    <!-- Enforce the use of a single space after the use, function, const keywords and both before and after the as keyword in import use statements -->
+    <rule ref="Universal.UseStatements.KeywordSpacing"/>
+
+    <!-- Enforce lowercase function/const -->
+    <rule ref="Universal.UseStatements.LowercaseFunctionConst"/>
+
+    <!-- Detect useless class imports (aliases) -->
+    <rule ref="Universal.UseStatements.NoUselessAliases"/>
+
+    <!-- Enfore comma, spacing, like, this -->
+    <rule ref="Universal.WhiteSpace.CommaSpacing"/>
+
+    <!--
+        TODO
+
+        PER-2.0 support (https://github.com/squizlabs/PHP_CodeSniffer/issues/3793), including:
+        - Trailing commas in function parameters https://github.com/squizlabs/PHP_CodeSniffer/issues/2030
+        - Multi-line implements/extends changes
+
+    -->
+
+</ruleset>