Skip to content

Commit b54bf3b

Browse files
jrfnlfredden
jrfnl
and
fredden
authored
GH Actions: add automation for generating output examples for the wiki (#20)
* GH Actions: prepare the workflow for auto-generating output snippets * Run phpcs/phpcbf commands to auto-generate output blocks * 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 --------- Co-authored-by: jrfnl <[email protected]> Co-authored-by: Dan Wallis <[email protected]>
1 parent 8a6e624 commit b54bf3b

File tree

7 files changed

+118
-190
lines changed

7 files changed

+118
-190
lines changed

‎.github/workflows/basic-qa.yml

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,3 +78,21 @@ jobs:
7878
- name: Fail the build when more spelling issues were found than expected
7979
if: ${{ always() && ( steps.spellcheck.outputs.number_of_issues != 3 || steps.spellcheck.outputs.number_of_files_with_issues != 2 ) }}
8080
run: exit 1
81+
82+
shellcheck:
83+
name: 'ShellCheck'
84+
runs-on: ubuntu-latest
85+
86+
steps:
87+
- name: Checkout code
88+
uses: actions/checkout@v4
89+
90+
- name: Set up problem matcher
91+
uses: lumaxis/shellcheck-problem-matchers@v2
92+
with:
93+
format: gcc
94+
95+
- name: Run ShellCheck
96+
uses: ludeeus/[email protected]
97+
with:
98+
format: gcc

‎.github/workflows/publish-wiki.yml

Lines changed: 39 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,9 @@ on:
1414
# Allow running this workflow manually from the Actions tab.
1515
workflow_dispatch:
1616
# Allow this workflow to be triggered from outside.
17+
repository_dispatch:
18+
types:
19+
- 'phpcs-release'
1720

1821
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
1922
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
@@ -38,6 +41,37 @@ jobs:
3841
- name: Checkout code
3942
uses: actions/checkout@v4
4043

44+
- name: Install PHP
45+
uses: shivammathur/setup-php@v2
46+
with:
47+
php-version: 'latest'
48+
ini-values: error_reporting=-1, display_errors=On, log_errors_max_len=0
49+
tools: phpcs, phpcbf
50+
coverage: none
51+
52+
# Make sure we've gotten the latest PHPCS version from setup-php.
53+
- name: Retrieve latest release info
54+
uses: octokit/[email protected]
55+
id: get_latest_release
56+
with:
57+
route: GET /repos/PHPCSStandards/PHP_CodeSniffer/releases/latest
58+
env:
59+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
60+
61+
- name: Grab latest tag name from API response
62+
id: latest_version
63+
run: |
64+
echo "TAG=${{ fromJson(steps.get_latest_release.outputs.data).tag_name }}" >> "$GITHUB_OUTPUT"
65+
66+
- name: Grab the version
67+
id: phar_version
68+
# yamllint disable-line rule:line-length
69+
run: echo "VERSION=$(phpcs --version | grep --only-matching --max-count=1 --extended-regexp '\b[0-9]+(\.[0-9]+)+')" >> "$GITHUB_OUTPUT"
70+
71+
- name: Fail the build if the PHAR is not the correct version
72+
if: ${{ steps.phar_version.outputs.VERSION != steps.latest_version.outputs.TAG }}
73+
run: exit 1
74+
4175

4276
# ################################################################################
4377
# Update Wiki files.
@@ -50,6 +84,10 @@ jobs:
5084
shell: bash
5185
run: cp -v -a wiki _wiki
5286

87+
- name: Find / replace output example placeholders
88+
shell: bash
89+
run: build/wiki-command-replacer.sh
90+
5391
- name: Update tables of contents
5492
run: doctoc ./_wiki/ --github --maxlevel 4 --update-only
5593

@@ -94,7 +132,7 @@ jobs:
94132
A dry-run has been executed on your PR, executing all markdown pre-processing for the wiki files.
95133
96134
Please review the resulting final markdown files via the [created artifact](${{ steps.artifact.outputs.artifact-url }}).
97-
This is especially important when adding new pages.
135+
This is especially important when adding new pages or updating auto-generated output blocks.
98136
99137
_N.B.: the above link will automatically be updated when this PR is updated._
100138

‎.shellcheckrc

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
shell=bash
2+
color=always
3+
4+
external-sources=false
5+
source-path=/build
6+
7+
# Turn on all checks.
8+
enable=all

‎build/wiki-code-samples/README.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# About This Directory
2+
3+
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.
4+
5+
Sometimes a command will need some code to run `phpcs`/`phpcbf` over to obtain the output to display in the wiki.
6+
7+
The code samples needed for this, should be placed in this directory.

‎build/wiki-command-replacer.sh

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
#!/usr/bin/env bash
2+
3+
set -eu -o pipefail
4+
5+
cd "$(dirname "$0")/.."
6+
7+
MARKER_START='{{COMMAND-OUTPUT "'
8+
MARKER_END='"}}'
9+
10+
if [[ -z "${CI:-}" ]]; then
11+
# The `_wiki` directory is created in a previous GitHub Action step.
12+
# This 'if' block is intended to assist with local development activity.
13+
rm -rf _wiki/
14+
cp -r wiki/ _wiki/
15+
fi
16+
17+
grep -lrF "${MARKER_START}" _wiki | while read -r file_to_process; do
18+
echo "Processing markers in ${file_to_process}"
19+
20+
while IFS=$'\n' read -r line; do
21+
if [[ ${line} = ${MARKER_START}*${MARKER_END} ]]; then
22+
COMMAND="${line##"${MARKER_START}"}"
23+
COMMAND="${COMMAND%%"${MARKER_END}"}"
24+
25+
if [[ "${COMMAND}" != "phpcs "* ]] && [[ "${COMMAND}" != "phpcbf "* ]]; then
26+
echo >&2 " ERROR: refusing to run arbitrary command: ${COMMAND}"
27+
exit 1
28+
fi
29+
30+
#FIXME refuse to run commands with a semicolon / pipe / ampersand / sub-shell
31+
32+
echo >&2 " INFO: running: ${COMMAND}"
33+
(
34+
eval "${COMMAND}" </dev/null || true
35+
)
36+
else
37+
echo "${line}"
38+
fi
39+
done < "${file_to_process}" > build/temp.md
40+
41+
mv build/temp.md "${file_to_process}"
42+
done

‎wiki/Fixing-Errors-Automatically.md

Lines changed: 1 addition & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -36,78 +36,7 @@ PHPCBF CAN FIX THE 2 MARKED SNIFF VIOLATIONS AUTOMATICALLY
3636

3737
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.
3838
```text
39-
Usage:
40-
phpcbf [options] <file|directory>
41-
42-
Scan targets:
43-
<file|directory> One or more files and/or directories to check, space separated.
44-
- Check STDIN instead of local files and directories.
45-
--stdin-path=<stdinPath> If processing STDIN, the file path that STDIN will be processed as.
46-
--file-list=<fileList> Check the files and/or directories which are defined in the file to which the
47-
path is provided (one per line).
48-
--filter=<filter> Check based on a predefined file filter. Use either the "GitModified" or
49-
"GitStaged" filter, or specify the path to a custom filter class.
50-
--ignore=<patterns> Ignore files based on a comma-separated list of patterns matching files and/or
51-
directories.
52-
--extensions=<extensions> Check files with the specified file extensions (comma-separated list).
53-
Defaults to php,inc/php,js,css.
54-
The type of the file can be specified using: ext/type; e.g. module/php,es/js.
55-
-l Check local directory only, no recursion.
56-
57-
Rule Selection Options:
58-
--standard=<standard> The name of, or the path to, the coding standard to use. Can be a
59-
comma-separated list specifying multiple standards. If no standard is
60-
specified, PHP_CodeSniffer will look for a [.]phpcs.xml[.dist] custom ruleset
61-
file in the current directory and those above it.
62-
--sniffs=<sniffs> A comma-separated list of sniff codes to limit the scan to. All sniffs must be
63-
part of the standard in use.
64-
--exclude=<sniffs> A comma-separated list of sniff codes to exclude from the scan. All sniffs
65-
must be part of the standard in use.
66-
67-
-i Show a list of installed coding standards.
68-
69-
Run Options:
70-
--bootstrap=<bootstrap> Run the specified file(s) before processing begins. A list of files can be
71-
provided, separated by commas.
72-
--parallel=<processes> The number of files to be checked simultaneously. Defaults to 1 (no parallel
73-
processing).
74-
If enabled, this option only takes effect if the PHP PCNTL (Process Control)
75-
extension is available.
76-
--suffix=<suffix> Write modified files to a filename using this suffix ("diff" and "patch" are
77-
not used in this mode).
78-
79-
-d <key[=value]> Set the [key] php.ini value to [value] or set to [true] if value is omitted.
80-
Note: only php.ini settings which can be changed at runtime are supported.
81-
82-
Reporting Options:
83-
--report-width=<reportWidth> How many columns wide screen reports should be. Set to "auto" to use current
84-
screen width, where supported.
85-
--basepath=<basepath> Strip a path from the front of file paths inside reports.
86-
87-
-w Include both warnings and errors (default).
88-
-n Do not include warnings. Shortcut for "--warning-severity=0".
89-
--severity=<severity> The minimum severity required to display an error or warning. Defaults to 5.
90-
--error-severity=<severity> The minimum severity required to display an error. Defaults to 5.
91-
--warning-severity=<severity> The minimum severity required to display a warning. Defaults to 5.
92-
93-
--ignore-annotations Ignore all "phpcs:..." annotations in code comments.
94-
--colors Use colors in screen output.
95-
--no-colors Do not use colors in screen output (default).
96-
-p Show progress of the run.
97-
-q Quiet mode; disables progress and verbose output.
98-
99-
Configuration Options:
100-
--encoding=<encoding> The encoding of the files being checked. Defaults to "utf-8".
101-
--tab-width=<tabWidth> The number of spaces each tab represents.
102-
103-
--runtime-set <key> <value> Set a configuration option to be applied to the current scan run only.
104-
105-
Miscellaneous Options:
106-
-h, -?, --help Print this help message.
107-
--version Print version information.
108-
-v Verbose output: Print processed files.
109-
-vv Verbose output: Print ruleset and token output.
110-
-vvv Verbose output: Print sniff processing information.
39+
{{COMMAND-OUTPUT "phpcbf --report-width=110 --no-colors -h"}}
11140
```
11241

11342
When using the PHPCBF command, you do not need to specify a report type. PHPCBF will automatically make changes to your source files:

‎wiki/Usage.md

Lines changed: 3 additions & 117 deletions
Original file line numberDiff line numberDiff line change
@@ -10,103 +10,7 @@
1010
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.
1111

1212
```text
13-
Usage:
14-
phpcs [options] <file|directory>
15-
16-
Scan targets:
17-
<file|directory> One or more files and/or directories to check, space separated.
18-
- Check STDIN instead of local files and directories.
19-
--stdin-path=<stdinPath> If processing STDIN, the file path that STDIN will be processed as.
20-
--file-list=<fileList> Check the files and/or directories which are defined in the file to which the
21-
path is provided (one per line).
22-
--filter=<filter> Check based on a predefined file filter. Use either the "GitModified" or
23-
"GitStaged" filter, or specify the path to a custom filter class.
24-
--ignore=<patterns> Ignore files based on a comma-separated list of patterns matching files
25-
and/or directories.
26-
--extensions=<extensions> Check files with the specified file extensions (comma-separated list).
27-
Defaults to php,inc/php,js,css.
28-
The type of the file can be specified using: ext/type; e.g. module/php,es/js.
29-
-l Check local directory only, no recursion.
30-
31-
Rule Selection Options:
32-
--standard=<standard> The name of, or the path to, the coding standard to use. Can be a
33-
comma-separated list specifying multiple standards. If no standard is
34-
specified, PHP_CodeSniffer will look for a [.]phpcs.xml[.dist] custom ruleset
35-
file in the current directory and those above it.
36-
--sniffs=<sniffs> A comma-separated list of sniff codes to limit the scan to. All sniffs must
37-
be part of the standard in use.
38-
--exclude=<sniffs> A comma-separated list of sniff codes to exclude from the scan. All sniffs
39-
must be part of the standard in use.
40-
41-
-i Show a list of installed coding standards.
42-
-e Explain a standard by showing the names of all the sniffs it includes.
43-
--generator=<generator> Show documentation for a standard. Use either the "HTML", "Markdown" or
44-
"Text" generator.
45-
46-
Run Options:
47-
-a Run in interactive mode, pausing after each file.
48-
--bootstrap=<bootstrap> Run the specified file(s) before processing begins. A list of files can be
49-
provided, separated by commas.
50-
--cache[=<cacheFile>] Cache results between runs. Optionally, <cacheFile> can be provided to use a
51-
specific file for caching. Otherwise, a temporary file is used.
52-
--no-cache Do not cache results between runs (default).
53-
--parallel=<processes> The number of files to be checked simultaneously. Defaults to 1 (no parallel
54-
processing).
55-
If enabled, this option only takes effect if the PHP PCNTL (Process Control)
56-
extension is available.
57-
58-
-d <key[=value]> Set the [key] php.ini value to [value] or set to [true] if value is omitted.
59-
Note: only php.ini settings which can be changed at runtime are supported.
60-
61-
Reporting Options:
62-
--report=<report(s)> A comma-separated list of reports to print. Available reports: "full", "xml",
63-
"checkstyle", "csv", "json", "junit", "emacs", "source", "summary", "diff",
64-
"svnblame", "gitblame", "hgblame", "notifysend" or "performance".
65-
Or specify the path to a custom report class. By default, the "full" report
66-
is displayed.
67-
--report-file=<reportFile> Write the report to the specified file path.
68-
--report-<report>=<reportFile> Write the report specified in <report> to the specified file path.
69-
--report-width=<reportWidth> How many columns wide screen reports should be. Set to "auto" to use current
70-
screen width, where supported.
71-
--basepath=<basepath> Strip a path from the front of file paths inside reports.
72-
73-
-w Include both warnings and errors (default).
74-
-n Do not include warnings. Shortcut for "--warning-severity=0".
75-
--severity=<severity> The minimum severity required to display an error or warning. Defaults to 5.
76-
--error-severity=<severity> The minimum severity required to display an error. Defaults to 5.
77-
--warning-severity=<severity> The minimum severity required to display a warning. Defaults to 5.
78-
79-
-s Show sniff error codes in all reports.
80-
--ignore-annotations Ignore all "phpcs:..." annotations in code comments.
81-
--colors Use colors in screen output.
82-
--no-colors Do not use colors in screen output (default).
83-
-p Show progress of the run.
84-
-q Quiet mode; disables progress and verbose output.
85-
-m Stop error messages from being recorded. This saves a lot of memory but stops
86-
many reports from being used.
87-
88-
Configuration Options:
89-
--encoding=<encoding> The encoding of the files being checked. Defaults to "utf-8".
90-
--tab-width=<tabWidth> The number of spaces each tab represents.
91-
92-
Default values for a selection of options can be stored in a user-specific CodeSniffer.conf configuration
93-
file.
94-
This applies to the following options: "default_standard", "report_format", "tab_width", "encoding",
95-
"severity", "error_severity", "warning_severity", "show_warnings", "report_width", "show_progress", "quiet",
96-
"colors", "cache", "parallel", "installed_paths", "php_version", "ignore_errors_on_exit",
97-
"ignore_warnings_on_exit".
98-
--config-show Show the configuration options which are currently stored in the applicable
99-
CodeSniffer.conf file.
100-
--config-set <key> <value> Save a configuration option to the CodeSniffer.conf file.
101-
--config-delete <key> Delete a configuration option from the CodeSniffer.conf file.
102-
--runtime-set <key> <value> Set a configuration option to be applied to the current scan run only.
103-
104-
Miscellaneous Options:
105-
-h, -?, --help Print this help message.
106-
--version Print version information.
107-
-v Verbose output: Print processed files.
108-
-vv Verbose output: Print ruleset and token output.
109-
-vvv Verbose output: Print sniff processing information.
13+
{{COMMAND-OUTPUT "phpcs --report-width=110 --no-colors -h"}}
11014
```
11115

11216
> [!NOTE]
@@ -290,7 +194,7 @@ PHP_CodeSniffer can print you a list of the coding standards that are installed
290194

291195
```bash
292196
$ phpcs -i
293-
The installed coding standards are MySource, PEAR, PSR1, PSR2, PSR12, Squiz and Zend
197+
{{COMMAND-OUTPUT "phpcs -i"}}
294198
```
295199

296200
<p align="right"><a href="#table-of-contents">back to top</a></p>
@@ -302,25 +206,7 @@ PHP_CodeSniffer can print you a list of the sniffs that a coding standard includ
302206

303207
```bash
304208
$ phpcs --standard=PSR1 -e
305-
306-
The PSR1 standard contains 8 sniffs
307-
308-
Generic (4 sniffs)
309-
------------------
310-
Generic.Files.ByteOrderMark
311-
Generic.NamingConventions.UpperCaseConstantName
312-
Generic.PHP.DisallowAlternativePHPTags
313-
Generic.PHP.DisallowShortOpenTag
314-
315-
PSR1 (3 sniffs)
316-
---------------
317-
PSR1.Classes.ClassDeclaration
318-
PSR1.Files.SideEffects
319-
PSR1.Methods.CamelCapsMethodName
320-
321-
Squiz (1 sniff)
322-
---------------
323-
Squiz.Classes.ValidClassName
209+
{{COMMAND-OUTPUT "phpcs --standard=PSR1 -e"}}
324210
```
325211

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

0 commit comments

Comments
 (0)