4.0 | Wiki: updates for change of the default standard from PEAR to PSR12

Includes automating various output example blocks via the automated replacement mechanism.

:warning: This commit should only be merged AFTER the PHPCS 4.0 release! The code samples used for the auto-generated output are specifically crafted to give errors/warnings against PSR12, not against the PEAR standard. :warning:
Note: this also means that the artifact containing the preprocessed output will need to be regenerated after the PHPCS 4.0 release to get an accurate representation of the updated wiki pages.

Where auto-generated output blocks was not an option, like when the output block in the documentation only displays part of a larger output stream, the command used to manually update the existing output block has been added as an inline comment.

Regarding the "diff" report - even with manually installing DiffUtils in GH Actions, the report does not display, so unless someone figures out why, this will need to be manually updated.

As for the "info" report, while this could be auto-generated using something like `{{COMMAND-OUTPUT "phpcs --parallel=1 --no-cache --no-colors --report-width=100 --report=info --basepath=build/wiki-code-samples build/wiki-code-samples/path/to/code/fileB.php build/wiki-code-samples/path/to/code/fileC.php"}}`, I believe the existing report example demonstrates the usecase for this report better, so I have deliberately not updated it.

Also not that for the "interactive" reporting code sample, I'm cheating a bit as interactive mode obviously cannot be auto-generated without user interaction, but we do know what the report should look like ;-)

Author: jrfnl

.github/workflows/basic-qa.yml

@@ -58,8 +58,6 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Spellcheck
-        id: spellcheck
-        continue-on-error: true
         uses: streetsidesoftware/cspell-action@v7
         with:
           # Define glob patterns to filter the files to be checked. Use a new line between patterns to define multiple patterns.
@@ -74,11 +72,6 @@ jobs:
           # Limit the files checked to the ones in the pull request or push.
           incremental_files_only: false
 
-      # Note: if less issues than expected were found, these numbers should be updated in the PR which fixes the issues!
-      - name: Fail the build when more spelling issues were found than expected
-        if: ${{ always() && ( steps.spellcheck.outputs.number_of_issues != 3 || steps.spellcheck.outputs.number_of_files_with_issues != 2 ) }}
-        run: exit 1
-
   shellcheck:
     name: 'ShellCheck'
     runs-on: ubuntu-latest

build/wiki-code-samples/path/to/code/fileA.php

@@ -0,0 +1,15 @@
+<?php
+/**
+ * File docblock.
+ */
+
+namespace Foo;
+
+class Bar
+{
+    public function baz( String  $param)
+    {
+        echo 'hello' . 'world and a lot more text to make this line way too long - trying to reach 120 characters, but that takes work';
+    return FALSE;
+    }
+}

build/wiki-code-samples/path/to/code/fileB.php

@@ -0,0 +1,7 @@
+<?php
+
+NAMESPACE Foo;
+
+if ($foo) {
+} else if ($bar) {
+}

build/wiki-code-samples/path/to/code/fileC.php

@@ -0,0 +1,6 @@
+<?php
+
+if ($foo) {
+} else if ($bar) {
+    echo 'hello' . 'world and a lot more text to make this line way too long - trying to reach 120 characters, but that takes work';
+}

wiki/About-Standards-for-PHP_CodeSniffer.md

@@ -50,7 +50,7 @@ You may also find the [Customisable Sniff Properties](https://github.com/PHPCSSt
 3. If no (project) ruleset file is found, PHP_CodeSniffer will check if a default standard has been set via `--config-set default_standard [Name]`.
     If so, PHP_CodeSniffer will use that standard.
     :warning: Setting the default standard is a user-specific setting, so should not be relied upon.
-4. If no system-default standard was set, PHP_CodeSniffer will apply the PEAR standard.
+4. If no system-default standard was set, PHP_CodeSniffer will apply the PSR12 standard.
 
 <p align="right"><a href="#table-of-contents">back to top</a></p>
 

wiki/Advanced-Usage.md

@@ -328,7 +328,7 @@ $ phpcs --config-show
 Using config file: path/to/PHP_CodeSniffer/CodeSniffer.conf
 
 colors:           1
-default_standard: PEAR
+default_standard: PSR12
 report_width:     150
 ```
 

wiki/Configuration-Options.md

@@ -7,7 +7,7 @@
 
 ## Setting the default coding standard
 
-By default, PHP_CodeSniffer will use the PEAR coding standard if no standard is supplied on the command line. You can change the default standard by setting the `default_standard` configuration option.
+By default, PHP_CodeSniffer will use the PSR12 coding standard if no standard is supplied on the command line. You can change the default standard by setting the `default_standard` configuration option.
 
 ```bash
 $ phpcs --config-set default_standard Squiz
@@ -16,6 +16,9 @@ $ phpcs --config-set default_standard Squiz
 > [!NOTE]
 > This configuration option cannot be set using the `--runtime-set` command line argument. To set the coding standard for a single run only, use the `--standard` command line argument.
 
+> [!NOTE]
+> Prior to PHP_CodeSniffer 4.0.0, PHP_CodeSniffer would default to the PEAR coding standard.
+
 <p align="right"><a href="#table-of-contents">back to top</a></p>
 
 

wiki/Fixing-Errors-Automatically.md

@@ -12,21 +12,8 @@ PHP_CodeSniffer is able to fix many errors and warnings automatically. The PHP C
 Screen-based reports, such as the [full](https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki/Reporting#printing-full-and-summary-reports), [summary](https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki/Reporting#printing-full-and-summary-reports) and [source](https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki/Reporting#printing-a-source-report) reports, provide information about how many errors and warnings are found. If any of the issues can be fixed automatically by `phpcbf`, this will be annotated in the report with the `[x]` markings:
 
 ```bash
-$ phpcs /path/to/code/myfile.php
-
-FILE: /path/to/code/myfile.php
---------------------------------------------------------------------------------
-FOUND 5 ERRORS AFFECTING 4 LINES
---------------------------------------------------------------------------------
- 2 | ERROR | [ ] Missing file doc comment
- 3 | ERROR | [x] TRUE, FALSE and NULL must be lowercase; expected "false" but
-   |       |     found "FALSE"
- 5 | ERROR | [x] Line indented incorrectly; expected at least 4 spaces, found 1
- 8 | ERROR | [ ] Missing function doc comment
- 8 | ERROR | [ ] Opening brace should be on a new line
---------------------------------------------------------------------------------
-PHPCBF CAN FIX THE 2 MARKED SNIFF VIOLATIONS AUTOMATICALLY
---------------------------------------------------------------------------------
+$ phpcs path/to/code/fileA.php
+{{COMMAND-OUTPUT "phpcs --parallel=1 --no-cache --no-colors --report-width=100 --basepath=build/wiki-code-samples build/wiki-code-samples/path/to/code/fileA.php"}}
 ```
 
 <p align="right"><a href="#table-of-contents">back to top</a></p>
@@ -97,32 +84,55 @@ A TOTAL OF 984 ERRORS WERE FIXED IN 2 FILES
 
 To see the fixes that are being made to a file, specify the `-vv` command line argument when generating a diff report. There is quite a lot of debug output concerning the standard being used and the tokenizing of the file, but the end of the output will look like this:
 
+<!--
+Regenerate the below output snippet by running the following command:
+$ phpcs -vv --parallel=1 --no-cache --no-colors --report-width=100 --report=diff --basepath=build/wiki-code-samples build/wiki-code-samples/path/to/code/fileB.php
+-->
 ```bash
 $ phpcs /path/to/file --report=diff -vv
 ..snip..
 *** START FILE FIXING ***
-E: [Line 3] Expected 1 space after "="; 0 found (Squiz.WhiteSpace.OperatorSpacing.NoSpaceAfter)
-Squiz_Sniffs_WhiteSpace_OperatorSpacingSniff (line 259) replaced token 4 (T_EQUAL) "=" => "=·"
+E: [Line 3] PHP keywords must be lowercase; expected "namespace" but found "NAMESPACE" (Generic.PHP.LowerCaseKeyword.Found)
+Generic.PHP.LowerCaseKeyword:76 replaced token 3 (T_NAMESPACE on line 3) "NAMESPACE" => "namespace"
 * fixed 1 violations, starting loop 2 *
 *** END FILE FIXING ***
 ```
 
 Sometimes the file may need to be processed multiple times in order to fix all the violations. This can happen when multiple sniffs need to modify the same part of a file, or if a fix causes a new sniff violation somewhere else in the standard. When this happens, the output will look like this:
 
+<!--
+Regenerate the below output snippet by running the following command:
+$ phpcs -vv --parallel=1 --no-cache --no-colors --report-width=100 --report=diff --basepath=build/wiki-code-samples build/wiki-code-samples/path/to/code/fileA.php
+-->
 ```bash
 $ phpcs /path/to/file --report=diff -vv
 ..snip..
 *** START FILE FIXING ***
-E: [Line 3] Expected 1 space before "="; 0 found (Squiz.WhiteSpace.OperatorSpacing.NoSpaceBefore)
-Squiz_Sniffs_WhiteSpace_OperatorSpacingSniff (line 228) replaced token 3 (T_EQUAL) "=" => "·="
-E: [Line 3] Expected 1 space after "="; 0 found (Squiz.WhiteSpace.OperatorSpacing.NoSpaceAfter)
-* token 3 has already been modified, skipping *
-E: [Line 3] Equals sign not aligned correctly; expected 1 space but found 0 spaces (Generic.Formatting.MultipleStatementAlignment.Incorrect)
-* token 3 has already been modified, skipping *
-* fixed 1 violations, starting loop 2 *
-E: [Line 3] Expected 1 space after "="; 0 found (Squiz.WhiteSpace.OperatorSpacing.NoSpaceAfter)
-Squiz_Sniffs_WhiteSpace_OperatorSpacingSniff (line 259) replaced token 4 (T_EQUAL) "=" => "=·"
-* fixed 1 violations, starting loop 3 *
+E: [Line 1] Header blocks must be separated by a single blank line (PSR12.Files.FileHeader.SpacingAfterTagBlock)
+PSR12.Files.FileHeader:311 replaced token 0 (T_OPEN_TAG on line 1) "<?php" => "<?php\n"
+E: [Line 13] Line indented incorrectly; expected at least 8 spaces, found 4 (Generic.WhiteSpace.ScopeIndent.Incorrect)
+Generic.WhiteSpace.ScopeIndent:1353 replaced token 51 (T_WHITESPACE on line 13) "    return" => "        return"
+E: [Line 10] PHP parameter type declarations must be lowercase; expected "string" but found "String" (Generic.PHP.LowerCaseType.ParamTypeFound)
+Generic.PHP.LowerCaseType:353 replaced token 33 (T_STRING on line 10) "String" => "string"
+E: [Line 10] Expected 1 space between type hint and argument "$param"; 2 found (Squiz.Functions.FunctionDeclarationArgumentSpacing.SpacingAfterHint)
+=> Changeset started by Squiz.Functions.FunctionDeclarationArgumentSpacing:291
+    Q: Squiz.Functions.FunctionDeclarationArgumentSpacing:292 replaced token 33 (T_STRING on line 10) "string" => "string "
+    Q: Squiz.Functions.FunctionDeclarationArgumentSpacing:295 replaced token 34 (T_WHITESPACE on line 10) "  $param" => "$param"
+    * token 33 has already been modified, skipping *
+=> Changeset failed to apply
+E: [Line 10] Expected 0 spaces after opening parenthesis; 1 found (Squiz.Functions.FunctionDeclarationArgumentSpacing.SpacingAfterOpen)
+Squiz.Functions.FunctionDeclarationArgumentSpacing:560 replaced token 32 (T_WHITESPACE on line 10) " string" => "string"
+E: [Line 13] TRUE, FALSE and NULL must be lowercase; expected "false" but found "FALSE" (Generic.PHP.LowerCaseConstant.Found)
+Generic.PHP.LowerCaseConstant:262 replaced token 54 (T_FALSE on line 13) "FALSE" => "false"
+* fixed 5 violations, starting loop 2 *
+E: [Line 11] Expected 1 space between type hint and argument "$param"; 2 found (Squiz.Functions.FunctionDeclarationArgumentSpacing.SpacingAfterHint)
+=> Changeset started by Squiz.Functions.FunctionDeclarationArgumentSpacing:291
+    Q: Squiz.Functions.FunctionDeclarationArgumentSpacing:292 replaced token 33 (T_STRING on line 11) "string" => "string "
+    Q: Squiz.Functions.FunctionDeclarationArgumentSpacing:295 replaced token 34 (T_WHITESPACE on line 11) "  $param" => "$param"
+    A: Squiz.Functions.FunctionDeclarationArgumentSpacing:298 replaced token 33 (T_STRING on line 11) "string" => "string "
+    A: Squiz.Functions.FunctionDeclarationArgumentSpacing:298 replaced token 34 (T_WHITESPACE on line 11) "  $param" => "$param"
+=> Changeset ended: 2 changes applied
+* fixed 2 violations, starting loop 3 *
 *** END FILE FIXING ***
 ```
 

wiki/Home.md

@@ -6,49 +6,21 @@ PHP_CodeSniffer is an essential development tool that ensures your code remains
 
 A coding standard in PHP_CodeSniffer is a collection of sniff files. Each sniff file checks one part of the coding standard only. Each sniff can yield multiple error codes, a different one for each aspect of the code which was checked and found non-compliant.
 
-Multiple coding standards can be used within PHP_CodeSniffer so that the one installation can be used across multiple projects. The default coding standard used by PHP_CodeSniffer is the PEAR coding standard.
+Multiple coding standards can be used within PHP_CodeSniffer so that the one installation can be used across multiple projects.  
+As of PHP_CodeSniffer 4.0.0, the default coding standard used by PHP_CodeSniffer is the PSR12 coding standard (previously, this was the PEAR standard).
 
 ## Example
 
-To check a file against the PEAR coding standard, simply specify the file's location.
+To check a file against the PSR12 coding standard, simply specify the file's location.
 
 ```bash
-$ phpcs /path/to/code/myfile.php
-
-FILE: /path/to/code/myfile.php
---------------------------------------------------------------------------------
-FOUND 5 ERROR(S) AFFECTING 2 LINE(S)
---------------------------------------------------------------------------------
-  2 | ERROR | Missing file doc comment
- 20 | ERROR | PHP keywords must be lowercase; expected "false" but found "FALSE"
- 47 | ERROR | Line not indented correctly; expected 4 spaces but found 1
- 51 | ERROR | Missing function doc comment
- 88 | ERROR | Line not indented correctly; expected 9 spaces but found 6
---------------------------------------------------------------------------------
+$ phpcs path/to/code/fileA.php
+{{COMMAND-OUTPUT "phpcs --parallel=1 --no-cache --no-colors --report-width=100 --basepath=build/wiki-code-samples build/wiki-code-samples/path/to/code/fileA.php"}}
 ```
 
 Or, if you wish to check an entire directory, you can specify the directory location instead of a file.
 
 ```bash
 $ phpcs /path/to/code
-
-FILE: /path/to/code/myfile.php
---------------------------------------------------------------------------------
-FOUND 5 ERROR(S) AFFECTING 5 LINE(S)
---------------------------------------------------------------------------------
-  2 | ERROR | Missing file doc comment
- 20 | ERROR | PHP keywords must be lowercase; expected "false" but found "FALSE"
- 47 | ERROR | Line not indented correctly; expected 4 spaces but found 1
- 51 | ERROR | Missing function doc comment
- 88 | ERROR | Line not indented correctly; expected 9 spaces but found 6
---------------------------------------------------------------------------------
-
-FILE: /path/to/code/yourfile.php
---------------------------------------------------------------------------------
-FOUND 1 ERROR(S) AND 1 WARNING(S) AFFECTING 1 LINE(S)
---------------------------------------------------------------------------------
- 21 | ERROR   | PHP keywords must be lowercase; expected "false" but found
-    |         | "FALSE"
- 21 | WARNING | Equals sign not aligned with surrounding assignments
---------------------------------------------------------------------------------
+{{COMMAND-OUTPUT "phpcs --parallel=1 --no-cache --no-colors --report-width=100 --basepath=build/wiki-code-samples build/wiki-code-samples/path/to/code"}}
 ```