diff --git a/.github/workflows/basic-qa.yml b/.github/workflows/basic-qa.yml index e412379..3547499 100644 --- a/.github/workflows/basic-qa.yml +++ b/.github/workflows/basic-qa.yml @@ -78,3 +78,21 @@ jobs: - 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 + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up problem matcher + uses: lumaxis/shellcheck-problem-matchers@v2 + with: + format: gcc + + - name: Run ShellCheck + uses: ludeeus/action-shellcheck@2.0.0 + with: + format: gcc diff --git a/.github/workflows/publish-wiki.yml b/.github/workflows/publish-wiki.yml index a81643b..27d15c8 100644 --- a/.github/workflows/publish-wiki.yml +++ b/.github/workflows/publish-wiki.yml @@ -14,6 +14,9 @@ on: # Allow running this workflow manually from the Actions tab. workflow_dispatch: # Allow this workflow to be triggered from outside. + repository_dispatch: + types: + - 'phpcs-release' # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. @@ -38,6 +41,37 @@ jobs: - name: Checkout code uses: actions/checkout@v4 + - name: Install PHP + uses: shivammathur/setup-php@v2 + with: + php-version: 'latest' + ini-values: error_reporting=-1, display_errors=On, log_errors_max_len=0 + tools: phpcs, phpcbf + coverage: none + + # Make sure we've gotten the latest PHPCS version from setup-php. + - name: Retrieve latest release info + uses: octokit/request-action@v2.x + id: get_latest_release + with: + route: GET /repos/PHPCSStandards/PHP_CodeSniffer/releases/latest + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - name: Grab latest tag name from API response + id: latest_version + run: | + echo "TAG=${{ fromJson(steps.get_latest_release.outputs.data).tag_name }}" >> "$GITHUB_OUTPUT" + + - name: Grab the version + id: phar_version + # yamllint disable-line rule:line-length + run: echo "VERSION=$(phpcs --version | grep --only-matching --max-count=1 --extended-regexp '\b[0-9]+(\.[0-9]+)+')" >> "$GITHUB_OUTPUT" + + - name: Fail the build if the PHAR is not the correct version + if: ${{ steps.phar_version.outputs.VERSION != steps.latest_version.outputs.TAG }} + run: exit 1 + # ################################################################################ # Update Wiki files. @@ -50,6 +84,10 @@ jobs: shell: bash run: cp -v -a wiki _wiki + - name: Find / replace output example placeholders + shell: bash + run: build/wiki-command-replacer.sh + - name: Update tables of contents run: doctoc ./_wiki/ --github --maxlevel 4 --update-only @@ -94,7 +132,7 @@ jobs: A dry-run has been executed on your PR, executing all markdown pre-processing for the wiki files. Please review the resulting final markdown files via the [created artifact](${{ steps.artifact.outputs.artifact-url }}). - This is especially important when adding new pages. + This is especially important when adding new pages or updating auto-generated output blocks. _N.B.: the above link will automatically be updated when this PR is updated._ diff --git a/.shellcheckrc b/.shellcheckrc new file mode 100644 index 0000000..e830edb --- /dev/null +++ b/.shellcheckrc @@ -0,0 +1,8 @@ +shell=bash +color=always + +external-sources=false +source-path=/build + +# Turn on all checks. +enable=all diff --git a/build/wiki-code-samples/README.md b/build/wiki-code-samples/README.md new file mode 100644 index 0000000..61f3d13 --- /dev/null +++ b/build/wiki-code-samples/README.md @@ -0,0 +1,7 @@ +# About This Directory + +The automation for the PHP_CodeSniffer wiki allows for running `phpcs`/`phpcbf` commands to generate output examples for the documentation using the `build/wiki-command-replacer.sh` script. + +Sometimes a command will need some code to run `phpcs`/`phpcbf` over to obtain the output to display in the wiki. + +The code samples needed for this, should be placed in this directory. diff --git a/build/wiki-command-replacer.sh b/build/wiki-command-replacer.sh new file mode 100755 index 0000000..048ba0e --- /dev/null +++ b/build/wiki-command-replacer.sh @@ -0,0 +1,42 @@ +#!/usr/bin/env bash + +set -eu -o pipefail + +cd "$(dirname "$0")/.." + +MARKER_START='{{COMMAND-OUTPUT "' +MARKER_END='"}}' + +if [[ -z "${CI:-}" ]]; then + # The `_wiki` directory is created in a previous GitHub Action step. + # This 'if' block is intended to assist with local development activity. + rm -rf _wiki/ + cp -r wiki/ _wiki/ +fi + +grep -lrF "${MARKER_START}" _wiki | while read -r file_to_process; do + echo "Processing markers in ${file_to_process}" + + while IFS=$'\n' read -r line; do + if [[ ${line} = ${MARKER_START}*${MARKER_END} ]]; then + COMMAND="${line##"${MARKER_START}"}" + COMMAND="${COMMAND%%"${MARKER_END}"}" + + if [[ "${COMMAND}" != "phpcs "* ]] && [[ "${COMMAND}" != "phpcbf "* ]]; then + echo >&2 " ERROR: refusing to run arbitrary command: ${COMMAND}" + exit 1 + fi + + #FIXME refuse to run commands with a semicolon / pipe / ampersand / sub-shell + + echo >&2 " INFO: running: ${COMMAND}" + ( + eval "${COMMAND}" build/temp.md + + mv build/temp.md "${file_to_process}" +done diff --git a/wiki/Fixing-Errors-Automatically.md b/wiki/Fixing-Errors-Automatically.md index d2901cc..b2c3f91 100644 --- a/wiki/Fixing-Errors-Automatically.md +++ b/wiki/Fixing-Errors-Automatically.md @@ -36,78 +36,7 @@ PHPCBF CAN FIX THE 2 MARKED SNIFF VIOLATIONS AUTOMATICALLY To automatically fix as many sniff violations as possible, use the `phpcbf` command instead of the `phpcs` command. While most of the PHPCS command line arguments can be used by PHPCBF, some are specific to reporting and will be ignored. Running PHPCBF with the `-h` or `--help` command line arguments will print a list of commands that PHPCBF will respond to. The output of `phpcbf -h` is shown below. ```text -Usage: - phpcbf [options] - -Scan targets: - One or more files and/or directories to check, space separated. - - Check STDIN instead of local files and directories. - --stdin-path= If processing STDIN, the file path that STDIN will be processed as. - --file-list= Check the files and/or directories which are defined in the file to which the - path is provided (one per line). - --filter= Check based on a predefined file filter. Use either the "GitModified" or - "GitStaged" filter, or specify the path to a custom filter class. - --ignore= Ignore files based on a comma-separated list of patterns matching files and/or - directories. - --extensions= Check files with the specified file extensions (comma-separated list). - Defaults to php,inc/php,js,css. - The type of the file can be specified using: ext/type; e.g. module/php,es/js. - -l Check local directory only, no recursion. - -Rule Selection Options: - --standard= The name of, or the path to, the coding standard to use. Can be a - comma-separated list specifying multiple standards. If no standard is - specified, PHP_CodeSniffer will look for a [.]phpcs.xml[.dist] custom ruleset - file in the current directory and those above it. - --sniffs= A comma-separated list of sniff codes to limit the scan to. All sniffs must be - part of the standard in use. - --exclude= A comma-separated list of sniff codes to exclude from the scan. All sniffs - must be part of the standard in use. - - -i Show a list of installed coding standards. - -Run Options: - --bootstrap= Run the specified file(s) before processing begins. A list of files can be - provided, separated by commas. - --parallel= The number of files to be checked simultaneously. Defaults to 1 (no parallel - processing). - If enabled, this option only takes effect if the PHP PCNTL (Process Control) - extension is available. - --suffix= Write modified files to a filename using this suffix ("diff" and "patch" are - not used in this mode). - - -d Set the [key] php.ini value to [value] or set to [true] if value is omitted. - Note: only php.ini settings which can be changed at runtime are supported. - -Reporting Options: - --report-width= How many columns wide screen reports should be. Set to "auto" to use current - screen width, where supported. - --basepath= Strip a path from the front of file paths inside reports. - - -w Include both warnings and errors (default). - -n Do not include warnings. Shortcut for "--warning-severity=0". - --severity= The minimum severity required to display an error or warning. Defaults to 5. - --error-severity= The minimum severity required to display an error. Defaults to 5. - --warning-severity= The minimum severity required to display a warning. Defaults to 5. - - --ignore-annotations Ignore all "phpcs:..." annotations in code comments. - --colors Use colors in screen output. - --no-colors Do not use colors in screen output (default). - -p Show progress of the run. - -q Quiet mode; disables progress and verbose output. - -Configuration Options: - --encoding= The encoding of the files being checked. Defaults to "utf-8". - --tab-width= The number of spaces each tab represents. - - --runtime-set Set a configuration option to be applied to the current scan run only. - -Miscellaneous Options: - -h, -?, --help Print this help message. - --version Print version information. - -v Verbose output: Print processed files. - -vv Verbose output: Print ruleset and token output. - -vvv Verbose output: Print sniff processing information. +{{COMMAND-OUTPUT "phpcbf --report-width=110 --no-colors -h"}} ``` When using the PHPCBF command, you do not need to specify a report type. PHPCBF will automatically make changes to your source files: diff --git a/wiki/Usage.md b/wiki/Usage.md index 17fad47..df5bf81 100644 --- a/wiki/Usage.md +++ b/wiki/Usage.md @@ -10,103 +10,7 @@ Running PHP_CodeSniffer with the `-h` or `--help` command line arguments will print a list of commands that PHP_CodeSniffer will respond to. The output of `phpcs -h` is shown below. ```text -Usage: - phpcs [options] - -Scan targets: - One or more files and/or directories to check, space separated. - - Check STDIN instead of local files and directories. - --stdin-path= If processing STDIN, the file path that STDIN will be processed as. - --file-list= Check the files and/or directories which are defined in the file to which the - path is provided (one per line). - --filter= Check based on a predefined file filter. Use either the "GitModified" or - "GitStaged" filter, or specify the path to a custom filter class. - --ignore= Ignore files based on a comma-separated list of patterns matching files - and/or directories. - --extensions= Check files with the specified file extensions (comma-separated list). - Defaults to php,inc/php,js,css. - The type of the file can be specified using: ext/type; e.g. module/php,es/js. - -l Check local directory only, no recursion. - -Rule Selection Options: - --standard= The name of, or the path to, the coding standard to use. Can be a - comma-separated list specifying multiple standards. If no standard is - specified, PHP_CodeSniffer will look for a [.]phpcs.xml[.dist] custom ruleset - file in the current directory and those above it. - --sniffs= A comma-separated list of sniff codes to limit the scan to. All sniffs must - be part of the standard in use. - --exclude= A comma-separated list of sniff codes to exclude from the scan. All sniffs - must be part of the standard in use. - - -i Show a list of installed coding standards. - -e Explain a standard by showing the names of all the sniffs it includes. - --generator= Show documentation for a standard. Use either the "HTML", "Markdown" or - "Text" generator. - -Run Options: - -a Run in interactive mode, pausing after each file. - --bootstrap= Run the specified file(s) before processing begins. A list of files can be - provided, separated by commas. - --cache[=] Cache results between runs. Optionally, can be provided to use a - specific file for caching. Otherwise, a temporary file is used. - --no-cache Do not cache results between runs (default). - --parallel= The number of files to be checked simultaneously. Defaults to 1 (no parallel - processing). - If enabled, this option only takes effect if the PHP PCNTL (Process Control) - extension is available. - - -d Set the [key] php.ini value to [value] or set to [true] if value is omitted. - Note: only php.ini settings which can be changed at runtime are supported. - -Reporting Options: - --report= A comma-separated list of reports to print. Available reports: "full", "xml", - "checkstyle", "csv", "json", "junit", "emacs", "source", "summary", "diff", - "svnblame", "gitblame", "hgblame", "notifysend" or "performance". - Or specify the path to a custom report class. By default, the "full" report - is displayed. - --report-file= Write the report to the specified file path. - --report-= Write the report specified in to the specified file path. - --report-width= How many columns wide screen reports should be. Set to "auto" to use current - screen width, where supported. - --basepath= Strip a path from the front of file paths inside reports. - - -w Include both warnings and errors (default). - -n Do not include warnings. Shortcut for "--warning-severity=0". - --severity= The minimum severity required to display an error or warning. Defaults to 5. - --error-severity= The minimum severity required to display an error. Defaults to 5. - --warning-severity= The minimum severity required to display a warning. Defaults to 5. - - -s Show sniff error codes in all reports. - --ignore-annotations Ignore all "phpcs:..." annotations in code comments. - --colors Use colors in screen output. - --no-colors Do not use colors in screen output (default). - -p Show progress of the run. - -q Quiet mode; disables progress and verbose output. - -m Stop error messages from being recorded. This saves a lot of memory but stops - many reports from being used. - -Configuration Options: - --encoding= The encoding of the files being checked. Defaults to "utf-8". - --tab-width= The number of spaces each tab represents. - - Default values for a selection of options can be stored in a user-specific CodeSniffer.conf configuration - file. - This applies to the following options: "default_standard", "report_format", "tab_width", "encoding", - "severity", "error_severity", "warning_severity", "show_warnings", "report_width", "show_progress", "quiet", - "colors", "cache", "parallel", "installed_paths", "php_version", "ignore_errors_on_exit", - "ignore_warnings_on_exit". - --config-show Show the configuration options which are currently stored in the applicable - CodeSniffer.conf file. - --config-set Save a configuration option to the CodeSniffer.conf file. - --config-delete Delete a configuration option from the CodeSniffer.conf file. - --runtime-set Set a configuration option to be applied to the current scan run only. - -Miscellaneous Options: - -h, -?, --help Print this help message. - --version Print version information. - -v Verbose output: Print processed files. - -vv Verbose output: Print ruleset and token output. - -vvv Verbose output: Print sniff processing information. +{{COMMAND-OUTPUT "phpcs --report-width=110 --no-colors -h"}} ``` > [!NOTE] @@ -290,7 +194,7 @@ PHP_CodeSniffer can print you a list of the coding standards that are installed ```bash $ phpcs -i -The installed coding standards are MySource, PEAR, PSR1, PSR2, PSR12, Squiz and Zend +{{COMMAND-OUTPUT "phpcs -i"}} ```

back to top

@@ -302,25 +206,7 @@ PHP_CodeSniffer can print you a list of the sniffs that a coding standard includ ```bash $ phpcs --standard=PSR1 -e - -The PSR1 standard contains 8 sniffs - -Generic (4 sniffs) ------------------- - Generic.Files.ByteOrderMark - Generic.NamingConventions.UpperCaseConstantName - Generic.PHP.DisallowAlternativePHPTags - Generic.PHP.DisallowShortOpenTag - -PSR1 (3 sniffs) ---------------- - PSR1.Classes.ClassDeclaration - PSR1.Files.SideEffects - PSR1.Methods.CamelCapsMethodName - -Squiz (1 sniff) ---------------- - Squiz.Classes.ValidClassName +{{COMMAND-OUTPUT "phpcs --standard=PSR1 -e"}} ```

back to top