Setting Up GitHub Actions for Automatic WPCS Verification: A Guide for PHP and WordPress

What is WPCS and Why Do You Need It?

WPCS (WordPress Coding Standards) is a set of coding standards designed to help developers create clean and maintainable code for WordPress. This guide explains configuring GitHub Actions for automatic code verification against WPCS using PHP versions 7.4 and higher.

How to Configure GitHub Actions for WPCS Verification

GitHub Actions allows you to automate code verification. With each commit to the main branch, your code will automatically be checked for WPCS compliance, helping to avoid errors and improve project quality.

Setting Up composer.json

To set up WPCS, add the following line to the ‘scripts’ section of your composer.json file:

"scripts": {
  "phpcs": "vendor/bin/phpcs --colors --standard=phpcs.xml"
}

This command specifies where to find the phpcs.xml configuration file.

Creating the phpcs.xml File

Create a phpcs.xml file in the root directory of your project. This file contains the rules for code verification. Here is an example configuration:

<?xml version="1.0"?>
<ruleset name="WPCS">
	<description>Coding Standards</description>

	<!-- What to scan -->
	<file>.</file>
	<exclude-pattern>*/\.github/*</exclude-pattern>
	<exclude-pattern>*/assets/*</exclude-pattern>
	<exclude-pattern>*/htmltofpdf/*</exclude-pattern>
	<exclude-pattern>*/languages/*</exclude-pattern>
	<exclude-pattern>*/node_modules/*</exclude-pattern>
	<exclude-pattern>*/src/js/*</exclude-pattern>
	<exclude-pattern>*/src/php/includes*</exclude-pattern>
	<exclude-pattern>*/vendor/*</exclude-pattern>
	<exclude-pattern>*\.js</exclude-pattern>
	<exclude-pattern>*\.mo</exclude-pattern>
	<exclude-pattern>*\.po</exclude-pattern>
	<exclude-pattern>*\.css</exclude-pattern>

	<!-- How to scan -->
	<arg value="sp"/><!-- Show sniff and progress -->
	<arg name="basepath" value="./"/><!-- Strip the file paths down to the relevant bit -->
	<arg name="extensions" value="php"/>
	<arg name="parallel" value="12"/><!-- Enables parallel processing when available for faster results. -->

	<config name="installed_paths" value="vendor/phpcompatibility/php-compatibility,vendor/phpcompatibility/phpcompatibility-paragonie,vendor/phpcompatibility/phpcompatibility-wp,vendor/wp-coding-standards/wpcs"/>
	<config name="testVersion" value="7.4-"/>

	<!-- Rules: Check PHP version compatibility -->
	<rule ref="PHPCompatibility"/>
	<rule ref="PHPCompatibilityWP"/>

	<!-- Rules: WordPress Coding Standards -->
	<config name="minimum_supported_wp_version" value="5.9"/>
	<rule ref="WordPress"/>

	<!-- Allow only short array syntax -->
	<rule ref="Generic.Arrays.DisallowShortArraySyntax.Found">
		<severity>0</severity>
	</rule>
	<rule ref="Generic.Arrays.DisallowLongArraySyntax.Found"/>

	<!-- Allow short ternary syntax -->
	<rule ref="WordPress.PHP.DisallowShortTernary.Found">
		<severity>0</severity>
	</rule>

	<!-- Rules to follow PSR4 -->
	<rule ref="WordPress.Files.FileName.InvalidClassFileName">
		<severity>0</severity>
	</rule>
	<rule ref="WordPress.Files.FileName.NotHyphenatedLowercase">
		<severity>0</severity>
	</rule>
</ruleset>

More information is available in the documentation

Configuring the ci.yml File

Create a .github/workflows directory and add a ci.yml file with the following configuration:

name: check WPCS

on: [ push, pull_request ]

jobs:
  cs_and_tests:
    strategy:
      matrix:
        os: [ ubuntu-latest ]
        php-version: [ '7.4', '8.0', '8.1', '8.2' ]
    env:
      wp-directory: wordpress
      wp-plugin-directory: wordpress/wp-content/plugins/your_folder

    runs-on: ${{ matrix.os }}

    name: PHP ${{ matrix.php-version }} on ${{ matrix.os }}

    steps:
      - name: Checkout code
        uses: actions/checkout@v3
        with:
          path: ${{ env.wp-plugin-directory }}

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php-version }}
          extensions: json, mysqli, mbstring, zip

      - name: Install dependencies with caching
        uses: ramsey/composer-install@v2
        with:
          working-directory: ${{ env.wp-plugin-directory }}

      - name: Run code sniffer
        working-directory: ${{ env.wp-plugin-directory }}
        run: composer phpcs

Ensure proper indentation, as YAML files are sensitive to formatting.

Let’s break down this file by key parameters that you need to modify:

1. php-version: [ ‘7.4’, ‘8.0’, ‘8.1’, ‘8.2’ ] — These are the PHP versions your code will be tested on.
2. wp-plugin-directory: wordpress/wp-content/plugins/your_folder_name
   You can name wp-plugin-directory however you like, as it is just an ENV variable. However, you must update this name consistently throughout the file. This represents the path to your code within the virtual machine.

These are the only changes you need to make in this file for it to work with your project.

Next, all you need to do is run git push to send all changes to your repository. To check how it works, navigate to your repository and the Actions tab. You should see something like this.

If your code fails the verification, go to the specific action run. There, you will find a detailed list of errors and issues in your code that need to be fixed to pass the test.

How to Fix WPCS Verification Errors

If the verification fails, GitHub Actions will display a list of errors. To resolve them:

1. Go to the Actions tab in your repository.
2. Open the detailed error report.
3. Fix the issues in your code.

After correcting the errors, run git push to trigger the verification again.

Conclusion

Setting up GitHub Actions for WPCS verification is a simple and effective way to improve code quality. Follow this guide to ensure your project adheres to WordPress standards. If you encounter difficulties, feel free to contact our team for professional assistance.