Using PHPCS and WordPress standards

It is very important that when we write code for ourselves or for our clients, we use standards.

This alone does not guarantee good code or even correct code, but at least it makes our code more readable for us in the future or for any other programmer who has to modify it. I already talked about this about three years ago in the post Why we shouldn’t use spaghetti code in WordPress.

A couple of days ago, in the entry My tools for daily work 2020 I told you how to install PHPCS, but I am going to remind you the process with some modifications and more complete.

Installing PHPCS and standards

The first thing to do is to download PHP locally, which is required for some tools.

In my case I use Windows, which is what I will indicate, but the process for iOS and Linux is similar.

I download version 7.4.7 and unzip it to the C drive in the c:\php directory.

I add PHP to the system environment variables from Configuration → About → System Information → Advanced System Settings → Environment Variables and there under System Variables I add c:\php to the path.

I check that everything is correct by running a console and from any directory I see that php -v returns the correct version information.

I continue to install Composer for PHP package management. From any directory I check that Composer is running correctly by looking at its version with composer --version (we update composer with composer self-update)

I install globally PHP Code Sniffer (phpcs) directly from composer with the command:

# composer global require "squizlabs/php_codesniffer=*"

and again I check that it works from any directory by returning its version with phpcs --version

I perform these command checks from the cmd console, the PowerShell console and from the Git Bash console. Obviously from WSL it will not work unless we install it in our Ubuntu, since it is a different subsystem.

Now we install the WordPress standards for phpcs, for which I first check the standards installed with phpcs -i and I see that the WordPress ones are not there.

In my profile folder (or in another folder of your choice) I create a new folder for my new phpcs standards and I call it phpcs_standards, so it will be C:\Users_standards\wpcs

I go into this folder and clone the repo for example in the wpcs folder with the command:

# git clone https://github.com/WordPress/WordPress-Coding-Standards wpcs

and then add the path to phpcs with the command:

# phpcs --config-set installed_paths C:\\Users\\carlos\\phpcs_standards\\wpcs

It is important in Windows to use the double slash, otherwise we will be escaping the character after the backslash.

And I check again with phpcs -i

Now that I have the WordPress standards configured, I go with the compatibility for PHP versions, for which I perform the same procedure as when installing the WordPress compatibility rules.

I clone the repo for example in the phpc folder with the command:

# git clone https://github.com/PHPCompatibility/PHPCompatibility phpc

I check the phpcs configuration, especially to see the path (added previously), since the parameter --config-set installed_pathsoverwrites any previous value:

# phpcs --config-show

and then add the path to phpcs with the command:

# phpcs --config-set installed_paths C:\\Users\\carlos\\phpcs_standards\\wpcs,C:\\Users\\carlos\\phpcs_standards\\phpc

this time I pass the previous path and after the comma the new path. I check again with phpcs -i

But we also have the PHPCompatibilityWP project that not only checks PHP compatibility, but also makes it specific for WordPress, excluding the back-fills and poly-fills provided by WordPress.

We are going to install it as before, cloning the repo, but first we see that among its requirements are PHP_CodeSniffer that we already have installed, PHPCompatibility that we also have installed and PHPCompatibilityParagonie that we are going to install together with this repo.

We execute the following:

# git clone https://github.com/PHPCompatibility/PHPCompatibilityParagonie phpcp
# git clone https://github.com/PHPCompatibility/PHPCompatibilityWP phpcwp
# phpcs --config-set installed_paths C:\\Users\\carlos\\phpcs_standards\\wpcs,C:\\Users\\carlos\\phpcs_standards\\phpc,C:\\Users\\carlos\\phpcs_standards\\phpcp,C:\\Users\\carlos\\phpcs_standards\\phpcwp

And we check again that the standards are already installed with phpcs -i

We can for example check from command line the compatibility of our files with php extension with the following command:

# phpcs -p *.php --standard=PHPCompatibilityWP

Although the ideal is to check directly on the fly from the editor itself.

Updating PHPCS and standards

To update phpcs we execute:

# composer global require squizlabs/php_codesniffer

To update the WordPress standards we go into the directory where we cloned the standards and get the latest version:

# cd C:\Users\carlos\phpcs_standards\wpcs
# git pull

To update PHP Compatibility we perform the same process in the directory we cloned over:

# cd C:\Users\carlos\phpcs_standards\phpc
# git pull

The same with PHPCompatibilityWP and PHPCompatibilityParagonie:

# cd C:\Users\carlos\phpcs_standards\phpcp
# git pull
# cd C:\Users\carlos\phpcs_standards\phpcwp
# git pull

If you get the following error when checking PHP version compatibility phpcs: Referenced sniff “PHPCS23Utils” does not exist change the PHPCompatibility repo branch to master and it should fix the problem (we change to master in both wpcs and phpc with git switch master).

Rule exceptions

If we do not want to be warned of an error, such as not using a version in our scripts or stylesheets to avoid the query string with the version number in our file, we can first see which rule we should ignore, by running pcpcs for our file with the WordPress standard:

# phpcs -s --standard=WordPress-Extra nuestro-archivo.php

And it will show us at the end and in brackets the rule to ignore, in our case WordPress.WP.EnqueuedResourceParameters.MissingVersion that we will put in our phpcs.ruleset.xml file of our project:

<rule ref="WordPress-Extra">
	<exclude name="WordPress.WP.EnqueuedResourceParameters.MissingVersion" />
</rule>

To show us the errors of the standards as we are writing in our editor (in my case Visual Studio Code), if we have everything well configured, we only have to install the extension in the editor, in this case the one called phpcs.

We have several configuration options, which, remember, can be applied globally for all our projects or for a specific project.

And finally, I leave you an example of a configuration file of rules of phpcs for a WordPress plugin that checks that the text_domain always be cl-menu-cache, I also ignore the missing version when queuing CSS and JS files (better for caching and something that many WPO testers ask us to do) and I test the compatibility of PHP versions from 7.4 onwards:

<?xml version="1.0"?>
<ruleset name="CL Menu Cache WordPress Plugin Coding Standards">

	<description>A custom set of code standard rules to check for WordPress plugin CL Menu Cache.</description>

	<rule ref="WordPress-Core" />
	<rule ref="WordPress-Docs" />
	<rule ref="WordPress-Extra" />

	<rule ref="WordPress.WP.I18n">
		<properties>
			<property name="text_domain" type="array" value="cl-menu-cache" />
		</properties>
	</rule>

	<rule ref="WordPress-Extra">
		<exclude name="WordPress.WP.EnqueuedResourceParameters.MissingVersion" />
	</rule>

	<!-- Run against the PHPCompatibilityWP ruleset -->
	<rule ref="PHPCompatibilityWP"/>

	<!-- Check for cross-version support for PHP 7.4 and higher -->
	<config name="testVersion" value="7.4-"/>

	<exclude-pattern>*/*.txt</exclude-pattern>
	<exclude-pattern>*/docs/*</exclude-pattern>
	<exclude-pattern>*/node_modules/*</exclude-pattern>
	<exclude-pattern>*/vendor/*</exclude-pattern>
</ruleset>

Updated 12/07/2023

If phpcs gives us an error ERROR: Referenced sniff "Universal.WhiteSpace.DisallowInlineTabs" does not exist we must go to the directory where we have installed the WordPress standards (wpcs if we follow the above instructions) and switch to the main branch (master in this case with git switch master) and we should work without error:

Update 07/21/2023: WooCommerce

We install the WooCommerce standards, although the ideal would be through composer as indicated in the repo, we will continue as above:

# git clone https://github.com/woocommerce/woocommerce-sniffs/ woocs
# phpcs --config-set installed_paths C:\\Users\\carlos\\phpcs_standards\\wpcs,C:\\Users\\carlos\\phpcs_standards\\phpc,C:\\Users\\carlos\\phpcs_standards\\phpcp,C:\\Users\\carlos\\phpcs_standards\\phpcwp,C:\\Users\\carlos\\phpcs_standards\\woocs\\src

In this case the path to be added has src at the end of it.