Add a new moodle-extra coding style

andrewnicols · Sep 15, 2023 · c0bc778 · c0bc778
1 parent 57bd4db
commit c0bc778
Show file tree

Hide file tree

Showing 4 changed files with 133 additions and 50 deletions.
diff --git a/CHANGELOG.md b/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).

diff --git a/README.md b/README.md
@@ -16,81 +16,73 @@
 
 ## Information
 
-This repository contains the Moodle Coding Style configuration.
+This repository contains the Moodle Coding Style configuration, written to support [PHP CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer).
+
+Two coding styles are included:
+
+- The standard `moodle` style, with support for a wider range of accepted Moodle standards; and
+- The more opinionated `moodle-extra` style, which extends the standard style and applies additional rules.
 
 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.
-
-
-### IDE Integration
+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.
 
-#### PhpStorm
+Additional configuration can be generated automatically to have PHP CodeSniffer ignore any third-party library code. This can be generated by running:
 
-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.
diff --git a/composer.json b/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": {

diff --git a/moodle-extra/ruleset.xml b/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>