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
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
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
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
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
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
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).
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>
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.