From fe56e5f8868416db7a8dec3e66de7a2157b935ca Mon Sep 17 00:00:00 2001 From: jrfnl Date: Sun, 12 Nov 2023 02:56:05 +0100 Subject: [PATCH] 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 ;-) --- .github/workflows/basic-qa.yml | 7 - .../wiki-code-samples/path/to/code/fileA.php | 15 + .../wiki-code-samples/path/to/code/fileB.php | 7 + .../wiki-code-samples/path/to/code/fileC.php | 6 + wiki/About-Standards-for-PHP_CodeSniffer.md | 2 +- wiki/Advanced-Usage.md | 2 +- wiki/Configuration-Options.md | 5 +- wiki/Fixing-Errors-Automatically.md | 64 ++-- wiki/Home.md | 40 +-- wiki/Reporting.md | 316 +++++------------- wiki/Usage.md | 79 ++--- 11 files changed, 175 insertions(+), 368 deletions(-) create mode 100644 build/wiki-code-samples/path/to/code/fileA.php create mode 100644 build/wiki-code-samples/path/to/code/fileB.php create mode 100644 build/wiki-code-samples/path/to/code/fileC.php diff --git a/.github/workflows/basic-qa.yml b/.github/workflows/basic-qa.yml index 3547499..b06000d 100644 --- a/.github/workflows/basic-qa.yml +++ b/.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 diff --git a/build/wiki-code-samples/path/to/code/fileA.php b/build/wiki-code-samples/path/to/code/fileA.php new file mode 100644 index 0000000..b4ed04e --- /dev/null +++ b/build/wiki-code-samples/path/to/code/fileA.php @@ -0,0 +1,15 @@ +back to top

diff --git a/wiki/Advanced-Usage.md b/wiki/Advanced-Usage.md index 25bc73e..9e33dbb 100644 --- a/wiki/Advanced-Usage.md +++ b/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 ``` diff --git a/wiki/Configuration-Options.md b/wiki/Configuration-Options.md index 528bfb3..7ad984c 100644 --- a/wiki/Configuration-Options.md +++ b/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. +

back to top

diff --git a/wiki/Fixing-Errors-Automatically.md b/wiki/Fixing-Errors-Automatically.md index 3a93df5..00af35c 100644 --- a/wiki/Fixing-Errors-Automatically.md +++ b/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"}} ```

back to top

@@ -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: + ```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: + ```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) " " " 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 *** ``` diff --git a/wiki/Home.md b/wiki/Home.md index 6d94d67..404615d 100644 --- a/wiki/Home.md +++ b/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"}} ``` diff --git a/wiki/Reporting.md b/wiki/Reporting.md index 1be376f..2ae00a5 100644 --- a/wiki/Reporting.md +++ b/wiki/Reporting.md @@ -29,64 +29,23 @@ When running a scan, by default, the full report is displayed. ```bash -$ phpcs /path/to/code/myfile.php - -FILE: /path/to/code/myfile.php --------------------------------------------------------------------------------- -FOUND 4 ERRORS AND 1 WARNING AFFECTING 5 LINES --------------------------------------------------------------------------------- - 2 | ERROR | [ ] Missing file doc comment - 4 | ERROR | [x] TRUE, FALSE and NULL must be lowercase; expected "false" but - | | found "FALSE" - 6 | ERROR | [x] Line indented incorrectly; expected at least 4 spaces, found - | | 1 - 9 | ERROR | [ ] Missing function doc comment - 11 | WARNING | [x] Inline control structures are discouraged --------------------------------------------------------------------------------- -PHPCBF CAN FIX THE 3 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"}} ``` To see a summary of the errors and warnings per file, use the `--report=summary` option. ```bash $ phpcs --report=summary /path/to/code - -PHP CODE SNIFFER REPORT SUMMARY --------------------------------------------------------------------------------- -FILE ERRORS WARNINGS --------------------------------------------------------------------------------- -/path/to/code/classA.inc 5 0 -/path/to/code/classB.inc 1 1 -/path/to/code/classC.inc 0 2 --------------------------------------------------------------------------------- -A TOTAL OF 6 ERROR(S) AND 3 WARNING(S) WERE FOUND IN 3 FILE(S) --------------------------------------------------------------------------------- +{{COMMAND-OUTPUT "phpcs --parallel=1 --no-cache --no-colors --report-width=100 --report=summary --basepath=build/wiki-code-samples build/wiki-code-samples/path/to/code"}} ``` The full report can also show information about the source of errors and warnings. To include source codes in the report, use the `-s` command line argument. ```bash -$ phpcs -s /path/to/code/myfile.php - -FILE: /path/to/code/myfile.php --------------------------------------------------------------------------------- -FOUND 4 ERRORS AND 1 WARNING AFFECTING 5 LINES --------------------------------------------------------------------------------- - 2 | ERROR | [ ] Missing file doc comment - | | (PEAR.Commenting.FileComment.Missing) - 4 | ERROR | [x] TRUE, FALSE and NULL must be lowercase; expected "false" but - | | found "FALSE" (Generic.PHP.LowerCaseConstant.Found) - 6 | ERROR | [x] Line indented incorrectly; expected at least 4 spaces, found - | | 1 (PEAR.WhiteSpace.ScopeIndent.Incorrect) - 9 | ERROR | [ ] Missing function doc comment - | | (PEAR.Commenting.FunctionComment.Missing) - 11 | WARNING | [x] Inline control structures are discouraged - | | (Generic.ControlStructures.InlineControlStructure.Discouraged) --------------------------------------------------------------------------------- -PHPCBF CAN FIX THE 3 MARKED SNIFF VIOLATIONS AUTOMATICALLY --------------------------------------------------------------------------------- +$ phpcs -s path/to/code/fileA.php +{{COMMAND-OUTPUT "phpcs -s --parallel=1 --no-cache --no-colors --report-width=100 --basepath=build/wiki-code-samples build/wiki-code-samples/path/to/code/fileA.php"}} ``` Source codes can be used with the `--sniffs` command line argument to only show messages from a specified list of sources @@ -102,42 +61,14 @@ PHP_CodeSniffer can output a summary report showing you the most common errors d ```bash $ phpcs --report=source /path/to/code - -PHP CODE SNIFFER VIOLATION SOURCE SUMMARY ------------------------------------------------------------------------------ -STANDARD CATEGORY SNIFF COUNT ------------------------------------------------------------------------------ -[x] PEAR White space Scope indent incorrect 1 -[x] Generic PHP Lower case constant found 1 -[x] Generic Control structures Inline control structure discouraged 1 -[ ] PEAR Commenting Function comment missing 1 -[ ] PEAR Commenting File comment missing 1 ------------------------------------------------------------------------------ -A TOTAL OF 5 SNIFF VIOLATIONS WERE FOUND IN 5 SOURCES ------------------------------------------------------------------------------ -PHPCBF CAN FIX THE 3 MARKED SOURCES AUTOMATICALLY (3 VIOLATIONS IN TOTAL) ------------------------------------------------------------------------------ +{{COMMAND-OUTPUT "phpcs --parallel=1 --no-cache --no-colors --report-width=100 --report=source --basepath=build/wiki-code-samples build/wiki-code-samples/path/to/code/fileA.php"}} ``` To show source codes instead of friendly names, use the `-s` command line argument. ```bash $ phpcs -s --report=source /path/to/code - -PHP CODE SNIFFER VIOLATION SOURCE SUMMARY ------------------------------------------------------------------------ -SOURCE COUNT ------------------------------------------------------------------------ -[x] Generic.ControlStructures.InlineControlStructure.Discouraged 1 -[x] PEAR.WhiteSpace.ScopeIndent.Incorrect 1 -[x] Generic.PHP.LowerCaseConstant.Found 1 -[ ] PEAR.Commenting.FunctionComment.Missing 1 -[ ] PEAR.Commenting.FileComment.Missing 1 ------------------------------------------------------------------------ -A TOTAL OF 5 SNIFF VIOLATIONS WERE FOUND IN 5 SOURCES ------------------------------------------------------------------------ -PHPCBF CAN FIX THE 3 MARKED SOURCES AUTOMATICALLY (3 VIOLATIONS IN TOTAL) ------------------------------------------------------------------------ +{{COMMAND-OUTPUT "phpcs -s --parallel=1 --no-cache --no-colors --report-width=100 --report=source --basepath=build/wiki-code-samples build/wiki-code-samples/path/to/code/fileA.php"}} ```

back to top

@@ -201,53 +132,8 @@ In the example above, the `Inline comment style` convention was checked 594 time PHP_CodeSniffer can output a report that shows a code snippet for each error and warning, showing the context in which the violation has occurred. The output will look like this: ```bash -$ phpcs --report=code /path/to/code - -FILE: /path/to/code/classA.php ------------------------------------------------------------------------------------------------- -FOUND 4 ERRORS AND 1 WARNING AFFECTING 5 LINES ------------------------------------------------------------------------------------------------- -LINE 2: ERROR [ ] Missing file doc comment ------------------------------------------------------------------------------------------------- - 1: > 2: - 3: if·($foo·===·null)·{ - 4: ····$foo·=·FALSE; ------------------------------------------------------------------------------------------------- -LINE 4: ERROR [x] TRUE, FALSE and NULL must be lowercase; expected "false" but found "FALSE" ------------------------------------------------------------------------------------------------- - 2: - 3: if·($foo·===·null)·{ ->> 4: ····$foo·=·FALSE; - 5: }·else·{ - 6: ·$foo·=·getFoo(); ------------------------------------------------------------------------------------------------- -LINE 6: ERROR [x] Line indented incorrectly; expected at least 4 spaces, found 1 ------------------------------------------------------------------------------------------------- - 4: ····$foo·=·FALSE; - 5: }·else·{ ->> 6: ·$foo·=·getFoo(); - 7: } - 8: ------------------------------------------------------------------------------------------------- -LINE 9: ERROR [ ] Missing function doc comment ------------------------------------------------------------------------------------------------- - 7: } - 8: ->> 9: function·getFoo() - 10: { - 11: ····if·($foo)·return·'foo'; ------------------------------------------------------------------------------------------------- -LINE 11: WARNING [x] Inline control structures are discouraged ------------------------------------------------------------------------------------------------- - 9: function·getFoo() - 10: { ->> 11: ····if·($foo)·return·'foo'; - 12: ····return·'bar'; - 13: } ------------------------------------------------------------------------------------------------- -PHPCBF CAN FIX THE 3 MARKED SNIFF VIOLATIONS AUTOMATICALLY ------------------------------------------------------------------------------------------------- +$ phpcs --report=code /path/to/code/fileA.php +{{COMMAND-OUTPUT "phpcs --parallel=1 --no-cache --no-colors --report-width=100 --report=code --basepath=build/wiki-code-samples build/wiki-code-samples/path/to/code/fileA.php"}} ``` > [!NOTE] @@ -264,16 +150,7 @@ PHP_CodeSniffer can output an XML report similar to the one produced by Checksty $ phpcs --report=checkstyle /path/to/code ``` ```xml - - - - - - - - - - +{{COMMAND-OUTPUT "phpcs --parallel=1 --no-cache --no-colors --report-width=100 --report=checkstyle --basepath=build/wiki-code-samples build/wiki-code-samples/path/to/code/fileA.php"}} ```

back to top

@@ -287,12 +164,7 @@ PHP_CodeSniffer can output a CSV report to allow you to parse the output and use $ phpcs --report=csv /path/to/code ``` ```csv -File,Line,Column,Type,Message,Source,Severity,Fixable -"/path/to/code/classA.php",2,1,error,"Missing file doc comment",PEAR.Commenting.FileComment.Missing,5,0 -"/path/to/code/classA.php",4,12,error,"TRUE, FALSE and NULL must be lowercase; expected \"false\" but found \"FALSE\"",Generic.PHP.LowerCaseConstant.Found,5,1 -"/path/to/code/classA.php",6,2,error,"Line indented incorrectly; expected at least 4 spaces, found 1",PEAR.WhiteSpace.ScopeIndent.Incorrect,5,1 -"/path/to/code/classA.php",9,1,error,"Missing function doc comment",PEAR.Commenting.FunctionComment.Missing,5,0 -"/path/to/code/classA.php",11,5,warning,"Inline control structures are discouraged",Generic.ControlStructures.InlineControlStructure.Discouraged,5,1 +{{COMMAND-OUTPUT "phpcs --parallel=1 --no-cache --no-colors --report-width=100 --report=csv --basepath=build/wiki-code-samples build/wiki-code-samples/path/to/code/fileA.php"}} ``` > [!IMPORTANT] @@ -308,23 +180,26 @@ File,Line,Column,Type,Message,Source,Severity,Fixable PHP_CodeSniffer can output a diff file that can be applied using the `patch` command. The suggested changes will fix some of the sniff violations that are present in the source code. To print a diff report, use the `--report=diff` command line argument. The output will look like this: + ```bash $ phpcs --report=diff /path/to/code ``` ```diff ---- /path/to/code/file.php +--- path/to/code/fileB.php +++ PHP_CodeSniffer -@@ -1,8 +1,8 @@ +@@ -1,7 +1,7 @@ [!NOTE] @@ -348,11 +223,7 @@ PHP_CodeSniffer can output a report in a format the compiler built into the GNU ```bash $ phpcs --report=emacs /path/to/code -/path/to/code/classA.php:2:1: error - Missing file doc comment -/path/to/code/classA.php:4:12: error - TRUE, FALSE and NULL must be lowercase; expected "false" but found "FALSE" -/path/to/code/classA.php:6:2: error - Line indented incorrectly; expected at least 4 spaces, found 1 -/path/to/code/classA.php:9:1: error - Missing function doc comment -/path/to/code/classA.php:11:5: warning - Inline control structures are discouraged +{{COMMAND-OUTPUT "phpcs --parallel=1 --no-cache --no-colors --report-width=100 --report=emacs --basepath=build/wiki-code-samples build/wiki-code-samples/path/to/code/fileA.php"}} ``` To use PHP_CodeSniffer with Emacs, make sure you have installed PHP mode for Emacs. Then put the following into your .emacs file, changing PHP_CodeSniffer options as required. @@ -360,7 +231,7 @@ To use PHP_CodeSniffer with Emacs, make sure you have installed PHP mode for Ema ```emacs (require 'compile) (defun my-php-hook-function () - (set (make-local-variable 'compile-command) (format "phpcs --report=emacs --standard=PEAR %s" (buffer-file-name)))) + (set (make-local-variable 'compile-command) (format "phpcs --report=emacs --standard=PSR12 %s" (buffer-file-name)))) (add-hook 'php-mode-hook 'my-php-hook-function) ``` @@ -450,74 +321,85 @@ A TOTAL OF 54 SNIFF VIOLATIONS WERE COMMITTED BY 6 AUTHORS PHP_CodeSniffer can output a JSON report to allow you to parse the output and use the results in your own scripts. To print a JSON report, use the `--report=json` command line argument. The output will look like this: + ```bash $ phpcs --report=json /path/to/code ``` ```json { "totals": { - "errors": 4, - "warnings": 1, - "fixable": 3 + "errors": 6, + "warnings": 0, + "fixable": 6 }, "files": { - "\/path\/to\/code\/classA.php": { - "errors": 4, - "warnings": 1, + "\/path\/to\/code\/fileA.php": { + "errors": 6, + "warnings": 0, "messages": [ - { - "message": "Missing file doc comment", - "source": "PEAR.Commenting.FileComment.Missing", + { + "message": "Header blocks must be separated by a single blank line", + "source": "PSR12.Files.FileHeader.SpacingAfterTagBlock", "severity": 5, + "fixable": true, "type": "ERROR", - "line": 2, - "column": 1, - "fixable": false + "line": 1, + "column": 1 }, { - "message": "TRUE, FALSE and NULL must be lowercase; expected \"false\" but found \"FALSE\"", - "source": "Generic.PHP.LowerCaseConstant.Found", + "message": "Expected 0 spaces after opening parenthesis; 1 found", + "source": "Squiz.Functions.FunctionDeclarationArgumentSpacing.SpacingAfterOpen", + "severity": 5, + "fixable": true, + "type": "ERROR", + "line": 10, + "column": 24 + }, + { + "message": "PHP parameter type declarations must be lowercase; expected \"string\" but found \"String\"", + "source": "Generic.PHP.LowerCaseType.ParamTypeFound", "severity": 5, + "fixable": true, "type": "ERROR", - "line": 4, - "column": 12, - "fixable": true + "line": 10, + "column": 26 }, { - "message": "Line indented incorrectly; expected at least 4 spaces, found 1", - "source": "PEAR.WhiteSpace.ScopeIndent.Incorrect", + "message": "Expected 1 space between type hint and argument \"$param\"; 2 found", + "source": "Squiz.Functions.FunctionDeclarationArgumentSpacing.SpacingAfterHint", "severity": 5, + "fixable": true, "type": "ERROR", - "line": 6, - "column": 2, - "fixable": true + "line": 10, + "column": 26 }, { - "message": "Missing function doc comment", - "source": "PEAR.Commenting.FunctionComment.Missing", + "message": "Line indented incorrectly; expected at least 8 spaces, found 4", + "source": "Generic.WhiteSpace.ScopeIndent.Incorrect", "severity": 5, + "fixable": true, "type": "ERROR", - "line": 9, - "column": 1, - "fixable": false + "line": 13, + "column": 5 }, { - "message": "Inline control structures are discouraged", - "source": "Generic.ControlStructures.InlineControlStructure.Discouraged", + "message": "TRUE, FALSE and NULL must be lowercase; expected \"false\" but found \"FALSE\"", + "source": "Generic.PHP.LowerCaseConstant.Found", "severity": 5, - "type": "WARNING", - "line": 11, - "column": 5, - "fixable": true + "fixable": true, + "type": "ERROR", + "line": 13, + "column": 12 } ] }, - "\/path\/to\/code\/classB.php": { + "\/path\/to\/code\/fileC.php": { "errors": 0, "warnings": 0, - "messages": [ - - ] + "messages": [] } } } @@ -534,29 +416,7 @@ PHP_CodeSniffer can output an XML report similar to the one produced by JUnit, a $ phpcs --report=junit /path/to/code ``` ```xml - - - - - - - - - - - - - - - - - - - - - - - +{{COMMAND-OUTPUT "phpcs -n --parallel=1 --no-cache --no-colors --report-width=100 --report=junit --basepath=build/wiki-code-samples build/wiki-code-samples/path/to/code/fileA.php build/wiki-code-samples/path/to/code/fileC.php"}} ```

back to top

@@ -627,16 +487,7 @@ PHP_CodeSniffer can output an XML report to allow you to parse the output and us $ phpcs --report=xml /path/to/code ``` ```xml - - - - Missing file doc comment - TRUE, FALSE and NULL must be lowercase; expected "false" but found "FALSE" - Line indented incorrectly; expected at least 4 spaces, found 1 - Missing function doc comment - Inline control structures are discouraged - - +{{COMMAND-OUTPUT "phpcs -n --parallel=1 --no-cache --no-colors --report-width=100 --report=xml --basepath=build/wiki-code-samples build/wiki-code-samples/path/to/code/fileA.php"}} ```

back to top

@@ -676,20 +527,7 @@ To run PHP_CodeSniffer interactively, use the `-a` command line argument. ```bash $ phpcs -a /path/to/code -FILE: /path/to/code/classA.php --------------------------------------------------------------------------------- -FOUND 4 ERRORS AND 1 WARNING AFFECTING 5 LINES --------------------------------------------------------------------------------- - 2 | ERROR | [ ] Missing file doc comment - 4 | ERROR | [x] TRUE, FALSE and NULL must be lowercase; expected "false" - | | but found "FALSE" - 6 | ERROR | [x] Line indented incorrectly; expected at least 4 spaces, - | | found 1 - 9 | ERROR | [ ] Missing function doc comment - 11 | WARNING | [x] Inline control structures are discouraged --------------------------------------------------------------------------------- -PHPCBF CAN FIX THE 3 MARKED SNIFF VIOLATIONS AUTOMATICALLY --------------------------------------------------------------------------------- +{{COMMAND-OUTPUT "phpcs -q --parallel=1 --no-cache --no-colors --report-width=100 --basepath=build/wiki-code-samples build/wiki-code-samples/path/to/code/fileA.php"}} to recheck, [s] to skip or [q] to quit : ``` diff --git a/wiki/Usage.md b/wiki/Usage.md index df5bf81..dc05b7f 100644 --- a/wiki/Usage.md +++ b/wiki/Usage.md @@ -14,7 +14,7 @@ Running PHP_CodeSniffer with the `-h` or `--help` command line arguments will pr ``` > [!NOTE] -> The `--standard` command line argument is optional, even if you have more than one coding standard installed. If no coding standard is specified, PHP_CodeSniffer will default to checking against the _PEAR_ coding standard, or the standard you have set as the default. [View instructions for setting the default coding standard](https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki/Configuration-Options#setting-the-default-coding-standard). +> The `--standard` command line argument is optional, even if you have more than one coding standard installed. If no coding standard is specified, PHP_CodeSniffer will default to checking against the _PSR12_ coding standard, or the standard you have set as the default. [View instructions for setting the default coding standard](https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki/Configuration-Options#setting-the-default-coding-standard).

back to top

@@ -39,37 +39,15 @@ $ phpcs /path/to/code/myfile.inc /path/to/code/my_dir After PHP_CodeSniffer has finished processing your files, you will get an error report. The report lists both errors and warnings for all files that violated the coding standard. The output looks like this: ```bash -$ phpcs /path/to/code/myfile.php - -FILE: /path/to/code/myfile.php --------------------------------------------------------------------------------- -FOUND 5 ERROR(S) AND 1 WARNING(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 - 47 | WARNING | Equals sign not aligned with surrounding assignments - 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"}} ``` If you don't want warnings included in the output, specify the `-n` command line argument. ```bash -$ phpcs -n /path/to/code/myfile.php - -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 --------------------------------------------------------------------------------- +$ phpcs -n path/to/code/fileA.php +{{COMMAND-OUTPUT "phpcs -n --parallel=1 --no-cache --no-colors --report-width=100 --basepath=build/wiki-code-samples build/wiki-code-samples/path/to/code/fileA.php"}} ```

back to top

@@ -81,33 +59,14 @@ By default, PHP_CodeSniffer will print a complete list of all errors and warning ```bash $ phpcs --report=summary /path/to/code - -PHP CODE SNIFFER REPORT SUMMARY --------------------------------------------------------------------------------- -FILE ERRORS WARNINGS --------------------------------------------------------------------------------- -/path/to/code/myfile.inc 5 0 -/path/to/code/yourfile.inc 1 1 -/path/to/code/ourfile.inc 0 2 --------------------------------------------------------------------------------- -A TOTAL OF 6 ERROR(S) AND 3 WARNING(S) WERE FOUND IN 3 FILE(S) --------------------------------------------------------------------------------- +{{COMMAND-OUTPUT "phpcs --parallel=1 --no-cache --no-colors --report-width=100 --report=summary --basepath=build/wiki-code-samples build/wiki-code-samples/path/to/code"}} ``` As with the full report, you can suppress the printing of warnings with the `-n` command line argument. ```bash $ phpcs -n --report=summary /path/to/code - -PHP CODE SNIFFER REPORT SUMMARY --------------------------------------------------------------------------------- -FILE ERRORS --------------------------------------------------------------------------------- -/path/to/code/myfile.inc 5 -/path/to/code/yourfile.inc 1 --------------------------------------------------------------------------------- -A TOTAL OF 6 ERROR(S) WERE FOUND IN 2 FILE(S) --------------------------------------------------------------------------------- +{{COMMAND-OUTPUT "phpcs -n --parallel=1 --no-cache --no-colors --report-width=100 --report=summary --basepath=build/wiki-code-samples build/wiki-code-samples/path/to/code"}} ```

back to top

@@ -145,18 +104,22 @@ Legend for the progress indicators: With verbose output enabled, PHP_CodeSniffer will print the file that it is checking, show you how many tokens and lines the file contains, and let you know how long it took to process. The output will look like this: + ```bash $ phpcs /path/to/project -v -Registering sniffs in PEAR standard... DONE (28 sniffs registered) -Creating file list... DONE (158 files in queue) +Registering sniffs in the PSR12 standard... DONE (60 sniffs registered) +Creating file list... DONE (79 files in queue) Changing into directory src/Standards/Generic/Sniffs/Arrays -Processing ArrayIndentSniff.php [1409 tokens in 193 lines]... DONE in 39ms (4 errors, 20 warnings) -Processing DisallowLongArraySyntaxSniff.php [405 tokens in 72 lines]... DONE in 11ms (0 errors, 4 warnings) -Processing DisallowShortArraySyntaxSniff.php [331 tokens in 61 lines]... DONE in 9ms (4 errors, 3 warnings) +Processing ArrayIndentSniff.php [1409 tokens in 193 lines]... DONE in 45ms (10 errors, 0 warnings) +Processing DisallowLongArraySyntaxSniff.php [405 tokens in 72 lines]... DONE in 13ms (8 errors, 0 warnings) +Processing DisallowShortArraySyntaxSniff.php [331 tokens in 61 lines]... DONE in 10ms (8 errors, 0 warnings) Changing into directory src/Standards/Generic/Sniffs/Classes -Processing DuplicateClassNameSniff.php [800 tokens in 118 lines]... DONE in 24ms (0 errors, 0 warnings) -Processing OpeningBraceSameLineSniff.php [936 tokens in 123 lines]... DONE in 26ms (4 errors, 12 warnings) +Processing DuplicateClassNameSniff.php [800 tokens in 118 lines]... DONE in 25ms (13 errors, 1 warnings) +Processing OpeningBraceSameLineSniff.php [936 tokens in 123 lines]... DONE in 29ms (12 errors, 1 warnings) ... ``` @@ -167,10 +130,10 @@ Processing OpeningBraceSameLineSniff.php [936 tokens in 123 lines]... DONE in 26 PHP_CodeSniffer can have multiple coding standards installed to allow a single installation to be used with multiple projects. When checking PHP code, PHP_CodeSniffer can be told which coding standard to use. This is done using the `--standard` command line argument. -The example below checks the `myfile.inc` file for violations against the _PEAR_ coding standard (installed by default). +The example below checks the `myfile.inc` file for violations against the _PSR12_ coding standard (installed by default). ```bash -$ phpcs --standard=PEAR /path/to/code/myfile.inc +$ phpcs --standard=PSR12 /path/to/code/myfile.inc ``` You can also tell PHP_CodeSniffer to use an external standard by specifying the full path to the standard's root directory on the command line. An external standard is one that is stored outside of PHP_CodeSniffer's `Standards` directory. @@ -182,7 +145,7 @@ $ phpcs --standard=/path/to/MyStandard /path/to/code/myfile.inc Multiple coding standards can be checked at the same time by passing a list of comma separated standards on the command line. A mix of external and installed coding standards can be passed if required. ```bash -$ phpcs --standard=PEAR,Squiz,/path/to/MyStandard /path/to/code/myfile.inc +$ phpcs --standard=PSR12,Squiz,/path/to/MyStandard /path/to/code/myfile.inc ```

back to top