Skip to content

GH Actions: add automation for generating output examples for the wiki #20

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jul 15, 2025
Merged

GH Actions: add automation for generating output examples for the wiki #20

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
73606a3
GH Actions: prepare the workflow for auto-generating output snippets
jrfnl Jun 17, 2025
4a232b5
Run phpcs/phpcbf commands to auto-generate output blocks
fredden Jun 23, 2025
4584545
GH Actions/basic QA: add shellcheck job
jrfnl Jun 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions .github/workflows/basic-qa.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/[email protected]
with:
format: gcc
40 changes: 39 additions & 1 deletion .github/workflows/publish-wiki.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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/[email protected]
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.
Expand All @@ -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

Expand Down Expand Up @@ -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._

Expand Down
8 changes: 8 additions & 0 deletions .shellcheckrc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
shell=bash
color=always

external-sources=false
source-path=/build

# Turn on all checks.
enable=all
7 changes: 7 additions & 0 deletions build/wiki-code-samples/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
42 changes: 42 additions & 0 deletions build/wiki-command-replacer.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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}" </dev/null || true
)
else
echo "${line}"
fi
done < "${file_to_process}" > build/temp.md

mv build/temp.md "${file_to_process}"
done
73 changes: 1 addition & 72 deletions wiki/Fixing-Errors-Automatically.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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] <file|directory>

Scan targets:
<file|directory> One or more files and/or directories to check, space separated.
- Check STDIN instead of local files and directories.
--stdin-path=<stdinPath> If processing STDIN, the file path that STDIN will be processed as.
--file-list=<fileList> Check the files and/or directories which are defined in the file to which the
path is provided (one per line).
--filter=<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=<patterns> Ignore files based on a comma-separated list of patterns matching files and/or
directories.
--extensions=<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=<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=<sniffs> A comma-separated list of sniff codes to limit the scan to. All sniffs must be
part of the standard in use.
--exclude=<sniffs> 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=<bootstrap> Run the specified file(s) before processing begins. A list of files can be
provided, separated by commas.
--parallel=<processes> 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=<suffix> Write modified files to a filename using this suffix ("diff" and "patch" are
not used in this mode).

-d <key[=value]> 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=<reportWidth> How many columns wide screen reports should be. Set to "auto" to use current
screen width, where supported.
--basepath=<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=<severity> The minimum severity required to display an error or warning. Defaults to 5.
--error-severity=<severity> The minimum severity required to display an error. Defaults to 5.
--warning-severity=<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=<encoding> The encoding of the files being checked. Defaults to "utf-8".
--tab-width=<tabWidth> The number of spaces each tab represents.

--runtime-set <key> <value> 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:
Expand Down
120 changes: 3 additions & 117 deletions wiki/Usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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] <file|directory>

Scan targets:
<file|directory> One or more files and/or directories to check, space separated.
- Check STDIN instead of local files and directories.
--stdin-path=<stdinPath> If processing STDIN, the file path that STDIN will be processed as.
--file-list=<fileList> Check the files and/or directories which are defined in the file to which the
path is provided (one per line).
--filter=<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=<patterns> Ignore files based on a comma-separated list of patterns matching files
and/or directories.
--extensions=<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=<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=<sniffs> A comma-separated list of sniff codes to limit the scan to. All sniffs must
be part of the standard in use.
--exclude=<sniffs> 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=<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=<bootstrap> Run the specified file(s) before processing begins. A list of files can be
provided, separated by commas.
--cache[=<cacheFile>] Cache results between runs. Optionally, <cacheFile> 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=<processes> 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 <key[=value]> 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=<report(s)> 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=<reportFile> Write the report to the specified file path.
--report-<report>=<reportFile> Write the report specified in <report> to the specified file path.
--report-width=<reportWidth> How many columns wide screen reports should be. Set to "auto" to use current
screen width, where supported.
--basepath=<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=<severity> The minimum severity required to display an error or warning. Defaults to 5.
--error-severity=<severity> The minimum severity required to display an error. Defaults to 5.
--warning-severity=<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=<encoding> The encoding of the files being checked. Defaults to "utf-8".
--tab-width=<tabWidth> 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 <key> <value> Save a configuration option to the CodeSniffer.conf file.
--config-delete <key> Delete a configuration option from the CodeSniffer.conf file.
--runtime-set <key> <value> 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]
Expand Down Expand Up @@ -183,8 +87,8 @@
FILE ERRORS WARNINGS
--------------------------------------------------------------------------------
/path/to/code/myfile.inc 5 0
/path/to/code/yourfile.inc 1 1

Check warning on line 90 in wiki/Usage.md

View workflow job for this annotation

GitHub Actions / Spellcheck 

Unknown word (yourfile) Suggestions: (outfile, oupfile, outFile, Outfile, houtfile)

Check warning on line 90 in wiki/Usage.md

View workflow job for this annotation

GitHub Actions / Spellcheck 

Unknown word (yourfile) Suggestions: (outfile, oupfile, outFile, Outfile, houtfile)
/path/to/code/ourfile.inc 0 2

Check warning on line 91 in wiki/Usage.md

View workflow job for this annotation

GitHub Actions / Spellcheck 

Unknown word (ourfile) Suggestions: (outfile, oupfile, outFile, Outfile, oupFile)

Check warning on line 91 in wiki/Usage.md

View workflow job for this annotation

GitHub Actions / Spellcheck 

Unknown word (ourfile) Suggestions: (outfile, oupfile, outFile, Outfile, oupFile)
--------------------------------------------------------------------------------
A TOTAL OF 6 ERROR(S) AND 3 WARNING(S) WERE FOUND IN 3 FILE(S)
--------------------------------------------------------------------------------
Expand Down Expand Up @@ -290,7 +194,7 @@

```bash
$ phpcs -i
The installed coding standards are MySource, PEAR, PSR1, PSR2, PSR12, Squiz and Zend
{{COMMAND-OUTPUT "phpcs -i"}}
```

<p align="right"><a href="#table-of-contents">back to top</a></p>
Expand All @@ -302,25 +206,7 @@

```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"}}
```

<p align="right"><a href="#table-of-contents">back to top</a></p>
Loading