Some questions have been around as long as software development. Should I indent with tabs or spaces? Are coding standards really that important? Do I really have to waste time following some arbitrary rules?
Respectively, the answers to these questions are: tabs (obviously), yes (less obviously) and no (sort of).
The importance of standards has been covered by others at length so I won’t go into detail here, but the crux of it is this: internal consistency is desirable within a given project because it improves readability, limits surprises, and can contribute to the robustness of code.
You don’t need to “waste time” sticking to standards because there are ways to apply those standards automatically!
What I’ll cover here is a means of quickly and easily setting up the standalone tool PHP Codesniffer (PHPCS) for WordPress projects. This will enable you to:
- Produce a report on standards compliance in your code
- Automatically resolve a wide variety of compliance issues
We’ll be implementing WordPress standards in the examples that follow.
- Terminal access (Windows users may have success with Bash for Windows but this is untested)
- Composer package manager
While it’s possible to install PHPCS by itself, it doesn’t support WordPress by default. For that, we’re going to install the snappily named WordPress Coding Standards (WPCS).
First, navigate to wherever you want to install WPCS for global use.
$ > cd /path/to/wherever
Install the package with composer.
$ > composer create-project wp-coding-standards/wpcs --no-dev
At this point, we could dive in and start using WPCS, but there are some flags to set each time we run the command. Let’s set up a couple of aliases for convenience.
Open .profile from your home directory in your favourite editor (or create it if it doesn’t exist) and add the following:
# WP Coding Standards export PATH=$PATH:"/path/to/wherever/wpcs/vendor/bin" alias wpcs='phpcs --standard=WordPress --extensions=php alias wpcbf='phpcbf --standard=WordPress --extensions=php
We’ve added two aliases here – one for phpcs (which finds and displays compliance failures) and one for phpcbf (which automatically fixes various issues found by phpcs). The additional options do the following:
–standard=WordPress – applies WordPress standards (set in WPCS)
–extensions=php – target PHP files only (PHPCS targets PHP, CSS and JS by default)
Restart the Terminal (or source .profile) and WPCS is ready to sniff your code!
To produce a sniff report on a file, run the following:
$ > wpcs /path/to/your/php/project/file.php
This will output the report in the terminal. Alternatively, you can output this to a file:
$ > wpcs /path/to/your/php/project/file.php > output.txt
The Sniff Report
Your WPCS sniff output will be something like this:
There’s a fair amount of information packed in here, but it’s quite cleanly laid out. Let’s review what we have:
- The targeted file
- A summary of how many errors/warnings were found, and number of affected lines
- A list of issues found, with severity levels and descriptions
- An indication of how many issues phpcbf can resolve automatically (basically all issues with an [x])
As might be expected, PHPCS can’t account for everything. It won’t make assumptions about punctuation choice in comments and certain kinds of code formatting, but it can handle a wide variety of issues for you.
A nice bonus is that the WordPress rules allow PHPCS to detect WordPress-specific issues, including potential misuse of functions.
Resolving issues automatically couldn’t be easier:
$ > wpcbf /path/to/your/php/project/file.php
A short summary is outputted:
Any remaining errors would need to be fixed manually, but you’ll usually find a good chunk of issues have been dealt with.
You may also wish to customise the ruleset, exclude certain directories in your project, and so forth. The PHPCS annotated ruleset docs provide examples of all the changes you can make, but broadly speaking you just:
- Create a ruleset file
- Reference it in the PHPCS command
Here’s an example of a ruleset file:
<?xml version="1.0"?> <ruleset name="WordPress Coding Standards"> <description>Customised WordPress standards.</description> <rule ref="WordPress"> <exclude name="Generic.Formatting.MultipleStatementAlignment.NotSameWarning"/> </rule> <exclude-pattern>*/bin/*</exclude-pattern> <exclude-pattern>*/node_modules/*</exclude-pattern> <exclude-pattern>*/tests/*</exclude-pattern> </ruleset>
In the example we’ve done the following:
- Referenced the WordPress ruleset (from WPCS)
- Excluded a rule
- Excluded some directories
The ruleset file can be placed in whatever directory you’re calling WPCS from (the project, theme, or plugin root is usually sensible) and referenced via a flag. Update the –standard flag in your .profile, like so:
# WP Coding Standards export PATH=$PATH:"/path/to/wherever/wpcs/vendor/bin" alias wpcs='phpcs --standard=codesniffer.ruleset.xml --extensions=php alias wpcbf='phpcbf --standard=codesniffer.ruleset.xml --extensions=php
To check which rules are being flagged when you run WPCS, simply run it with the -s flag like so:
$ > wpcs -s /path/to/your/php/project/file.php
The above guide will empower you to perform ad-hoc standards compliance checks in your WordPress project, but if you want to integrate it into your standard development cycle then the next logical step is automation.
Consider integrating PHPCS into a task runner such as gulp or grunt (PHPCS modules are available for both), or otherwise integrating it into your CI/CD build pipeline.
For help with web development and design, get in touch with us today.