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 the 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 a 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 checkon: pull_requestjobs:
phpcs:
name: WPCSruns-on: ubuntu-lateststeps:
- uses: actions/checkout@v4
- name: WPCS checkuses: 10up/wpcs-action@stable

Available options (with default value):

...
- name: WPCS checkuses: 10up/wpcs-action@stablewith:
enable_warnings: false # Enable checking for warnings (-w)paths: '.'# Paths to check, space separatedexcludes: ''# Paths to excludes, space separatedstandard: '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 standardrepo_branch: 'master'# Branch of Standard repositoryphpcs_bin_path: 'phpcs'# Custom PHPCS bin pathuse_local_config: 'false'# Use local config if availableextra_args: ''# Extra arguments passing to the commandonly_changed_files: ''# Run the linter only on the changed files. Accepts true|falseonly_changed_lines: ''# Run the linter only on the changed lines. Accepts true|false

Examples

VIP Coding Standards

name: WPCS checkon: pull_requestjobs:
phpcs:
name: VIPCSruns-on: ubuntu-lateststeps:
- uses: actions/checkout@v4
- name: VIPCS checkuses: 10up/wpcs-action@stablewith:
standard: 'WordPress-VIP-Go'

Display the linting result in the GitHub Actions summary

name: WPCS checkon: pull_requestjobs:
phpcs:
name: VIPCSruns-on: ubuntu-lateststeps:
- uses: actions/checkout@v4
- name: VIPCS checkuses: 10up/wpcs-action@stablewith:
standard: 'WordPress-VIP-Go'extra_args: '--report-json=./phpcs.json'
- name: Update summaryrun: | npm i -g github:10up/phpcs-json-to-md phpcs-json-to-md --path ./phpcs.json --output ./phpcs.md cat phpcs.md >> $GITHUB_STEP_SUMMARYif: 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"?>
<rulesetname="Project Rules">
<ruleref="WordPress">
<!-- Any of `WordPress|WordPress-Core|WordPress-Docs|WordPress-Extra|WordPress-VIP-Go|WordPressVIPMinimum|10up-Default` -->
<excludename="WordPress.Files.FileName.NotHyphenatedLowercase" />
<excludename="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: WPCSruns-on: ubuntu-lateststeps:
- uses: actions/checkout@v4
- name: WPCS checkuses: 10up/wpcs-action@stablewith:
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 checkon: pull_requestjobs:
phpcs:
name: WPCSruns-on: ubuntu-lateststeps:
- uses: actions/checkout@v4with:
fetch-depth: 0# This is very important. Without this the linting of only the changed lines will not work.
- name: WPCS checkuses: 10up/wpcs-action@stablewith:
standard: 10up-Defaultenable_warnings: trueonly_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.

Like what you see?