From 73606a38bbfc2a613aae08b31d5dd099f6873188 Mon Sep 17 00:00:00 2001
From: jrfnl
Date: Tue, 17 Jun 2025 17:55:47 +0200
Subject: [PATCH 1/3] GH Actions: prepare the workflow for auto-generating
output snippets
---
.github/workflows/publish-wiki.yml | 36 +++++++++++++++++++++++++++++-
1 file changed, 35 insertions(+), 1 deletion(-)
diff --git a/.github/workflows/publish-wiki.yml b/.github/workflows/publish-wiki.yml
index a81643b..7c6eceb 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.
@@ -94,7 +128,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._
From 4a232b5a72b2181efb79de76902d472bc6fba2b3 Mon Sep 17 00:00:00 2001
From: Dan Wallis
Date: Mon, 23 Jun 2025 14:33:18 +0100
Subject: [PATCH 2/3] Run phpcs/phpcbf commands to auto-generate output blocks
---
.github/workflows/publish-wiki.yml | 4 +
build/wiki-code-samples/README.md | 7 ++
build/wiki-command-replacer.sh | 42 ++++++++++
wiki/Fixing-Errors-Automatically.md | 73 +----------------
wiki/Usage.md | 120 +---------------------------
5 files changed, 57 insertions(+), 189 deletions(-)
create mode 100644 build/wiki-code-samples/README.md
create mode 100755 build/wiki-command-replacer.sh
diff --git a/.github/workflows/publish-wiki.yml b/.github/workflows/publish-wiki.yml
index 7c6eceb..27d15c8 100644
--- a/.github/workflows/publish-wiki.yml
+++ b/.github/workflows/publish-wiki.yml
@@ -84,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
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}" < "${file_to_process}" > 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
From 45845457689c12674a37fce325543e8936a6b37e Mon Sep 17 00:00:00 2001
From: jrfnl
Date: Mon, 23 Jun 2025 13:36:13 +0200
Subject: [PATCH 3/3] GH Actions/basic QA: add shellcheck job
As this repo now contains a shell script to find & replace placeholders for output snippets in the wiki files with real output, let's also run a minimal QA check on the code of the shell script.
Refs:
* https://github.com/koalaman/shellcheck
* https://github.com/koalaman/shellcheck/wiki
---
.github/workflows/basic-qa.yml | 18 ++++++++++++++++++
.shellcheckrc | 8 ++++++++
2 files changed, 26 insertions(+)
create mode 100644 .shellcheckrc
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/.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