Awesome
WPCS GitHub Action
GitHub Action to help you lint your PHP without additional dependencies within your codebase.
Overview
This action will help you to run phpcs (PHP_CodeSniffer) against WordPress Coding Standards with GitHub Actions platform.
To make it as simple as possible, this action supports WordPress Coding Standards exclusively and only checks for PHP files. This action doesn't require any change or addition to your source code. It means that you don't need to add composer/phpcs to your plugin or create PHP CodeSniffer config to use this action.
This is a fork of chekalsky/phpcs-action, so this action supports GitHub Action annotations too. All credit goes to Ilya Chekalsky.
From v1.3.1, this action can detect the PHPCS custom config and use that config to check the source code. When using the local config, paths, excludes, and standard are ignored.
☞ Check out our collection of WordPress-focused GitHub Actions
Known Caveats/Issues
Annotations limit
GitHub allows only 10 warning annotations and 10 error annotations per step. So any warning/error exceeds this threshold won't show on the GitHub Pull Request page.
Usage
Add the following code to .github/workflows/wpcs.yml file.
name: WPCS check
on: pull_request
jobs:
phpcs:
name: WPCS
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: WPCS check
uses: 10up/wpcs-action@stable
Available options (with default value):
...
- name: WPCS check
uses: 10up/wpcs-action@stable
with:
enable_warnings: false # Enable checking for warnings (-w)
paths: '.' # Paths to check, space separated
excludes: '' # Paths to excludes, space separated
standard: 'WordPress' # Standard to use. Accepts WordPress|WordPress-Core|WordPress-Docs|WordPress-Extra|WordPress-VIP-Go|WordPressVIPMinimum|10up-Default.
standard_repo: '' # Public (git) repository URL of the coding standard
repo_branch: 'master' # Branch of Standard repository
phpcs_bin_path: 'phpcs' # Custom PHPCS bin path
use_local_config: 'false' # Use local config if available
extra_args: '' # Extra arguments passing to the command
only_changed_files: '' # Run the linter only on the changed files. Accepts true|false
only_changed_lines: '' # Run the linter only on the changed lines. Accepts true|false
Examples
VIP Coding Standards
name: WPCS check
on: pull_request
jobs:
phpcs:
name: VIPCS
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: VIPCS check
uses: 10up/wpcs-action@stable
with:
standard: 'WordPress-VIP-Go'
Display the linting result in the GitHub Actions summary
name: WPCS check
on: pull_request
jobs:
phpcs:
name: VIPCS
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: VIPCS check
uses: 10up/wpcs-action@stable
with:
standard: 'WordPress-VIP-Go'
extra_args: '--report-json=./phpcs.json'
- name: Update summary
run: |
npm i -g github:10up/phpcs-json-to-md
phpcs-json-to-md --path ./phpcs.json --output ./phpcs.md
cat phpcs.md >> $GITHUB_STEP_SUMMARY
if: always()
Exclude specific rule(s) from the used ruleset
Create a custom project ruleset by creating file named phpcs.xml.dist in the root directory of the project. The contents of the file should be similar to the following:
<?xml version="1.0"?>
<ruleset name="Project Rules">
<rule ref="WordPress">
<!-- Any of `WordPress|WordPress-Core|WordPress-Docs|WordPress-Extra|WordPress-VIP-Go|WordPressVIPMinimum|10up-Default` -->
<exclude name="WordPress.Files.FileName.NotHyphenatedLowercase" />
<exclude name="WordPress.Files.FileName.InvalidClassFileName" />
</rule>
</ruleset>
When setting up the workflow for the project, to use the custom project ruleset, the use_local_config arguments will need to be set to true to instruct the action to use the local project file. The job configuration should be similar to the following:
jobs:
phpcs:
name: WPCS
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: WPCS check
uses: 10up/wpcs-action@stable
with:
standard: 'WordPress' # Standard to use. Accepts WordPress|WordPress-Core|WordPress-Docs|WordPress-Extra|WordPress-VIP-Go|WordPressVIPMinimum|10up-Default.
use_local_config: 'true'
Run linter on changed lines
name: WPCS check
on: pull_request
jobs:
phpcs:
name: WPCS
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0 # This is very important. Without this the linting of only the changed lines will not work.
- name: WPCS check
uses: 10up/wpcs-action@stable
with:
standard: 10up-Default
enable_warnings: true
only_changed_lines: true
Support Level
Active: 10up is actively working on this, and we expect to continue work for the foreseeable future including keeping tested up to the most recent version of WordPress. Bug reports, feature requests, questions, and pull requests are welcome.
Changelog
A complete listing of all notable changes to this project are documented in CHANGELOG.md.
Contributing
Please read CODE_OF_CONDUCT.md for details on our code of conduct, CONTRIBUTING.md for details on the process for submitting pull requests to us, and CREDITS.md for a listing of maintainers, contributors, and libraries for this project.