PHPCS Code Linting for Wordpress

‘Linting’ automatically analyses your code for potential errors and ensures it’s formatted according to a definition. There are tools to lint your code across many programming language and can be customised on a per project basis to increase code quality & consistency, improved performance and reduce developer decision making fatigue.

This guide will help you setup Code Linting for your Wordpress project.

1. Installation

Using Composer — Install PHPCS and the Wordpress Coding Standards, to your local machine:

composer global require squizlabs/php_codesniffer wp-coding-standards/wpcs

Add the Wordpress Coding Standard to the PHPCS list of available standards:

# Windows/Mac
phpcs --config-set installed_paths ~/.composer/vendor/wp-coding-standards/wpcs
# Ubuntu
phpcs --config-set installed_paths ~/.config/composer/vendor/wp-coding-standards/wpcs

To test it’s working, from the command line, you should now be able to run:

phpcs -i

Which will return:

The installed coding standards are PEAR, Zend, PSR2, MySource, Squiz, PSR1, PSR12, WordPress, WordPress-Extra, WordPress-Docs and WordPress-Core

2. Project Config

The first step is to setup project-specific linting configuration. There’s a couple of benefits in making it project-specific (opposed to globally defining config):

1. The config can be shared across team members
2. You can use different config for different projects — a Wordpress code style guide for Wordpress projects but not a Laravel project for example

In the root (or perhaps even just in your theme or plugin — depends on how much you’re writing) of your project, track the following phpcs.xml file (note that this is for Wordpress):

To lint a single file through the Wordpress Code Standards — eg. the header.php, you can now run:

phpcs header.php

For me, this returned the follow error because I had a function like so: function foo($bar) however Wordpress Standards want it like so: function foo( $bar )

FILE: /Users/Matt/Sites/pvtl/web/app/themes/pvtl/header.php
--------------------------------------------------------------------
FOUND 1 ERROR AFFECTING 1 LINE
--------------------------------------------------------------------
1 | ERR | [x] No space before closing parenthesis is prohibited
(WordPress.WhiteSpace.ControlStructureSpacing.NoSpaceBeforeCloseParenthesis)
--------------------------------------------------------------------
PHPCBF CAN FIX THE 1 MARKED SNIFF VIOLATIONS AUTOMATICALLY
--------------------------------------------------------------------
Time: 243ms; Memory: 8Mb

3. Realtime Feedback

PHPCS is now working in our terminal, however the real benefit comes from error and standards checking in realtime. We can setup our IDEs to give us this immediate feedback as we code.

3.1 VS Code

There are plugins/extensions for most IDEs, I’ll highlight how to set it up in Visual Studio Code (VSCode):

1. Install the VSCode PHPCS extension
2. Open settings.json (CMD + Shift+ P) and add the following to the settings object (replacing <absolute/path/to> with your own path):

Windows/Mac:

"phpcs.executablePath": "/<absolute/path/to>/.composer/vendor/squizlabs/php_codesniffer/bin/phpcs",
"phpcs.standard": "./phpcs.xml",

Ubuntu:

"phpcs.executablePath": "/<absolute/path/to>/.config/composer/vendor/squizlabs/php_codesniffer/bin/phpcs",
"phpcs.standard": "./phpcs.xml",

From the ‘Problems’ tab (CMD+Shift+P ‘View: Toggle Problems’) — you’ll see the linting errors. You’ll also notice the red underlines within the code.

3.2 Sublime Text

1. Install the SublimeLinter and SublimeLinter-phpcs extensions
2. Open Preferences.sublime-settings (CMD + ,) and add the following to the settings object (you can use which phpcs to find the path to PHPCS):

Windows/Mac:

"SublimeLinter.linters.phpcs.executable": "~/.composer/vendor/bin/phpcs",

Ubuntu:

"SublimeLinter.linters.phpcs.executable": "~/.config/composer/vendor/bin/phpcs",

From there, you can use the command palette (CMD + p) to “show all errors” and then “lint this view”. I personally edit the SublimeLinter’s settings, to make the linting happen in the background (“lint_mode”: “background”).