Skip to content

How-to Guides

Technical References

Code Review /

Install PHP_CodeSniffer for WordPress VIP

Did you know that you could get much of the feedback given by the VIP team shown to you in real-time, as you code?

PHP_CodeSniffer (PHPCS) is a tool that will help you write VIP-approved code by ensuring it meets the VIP coding standards. Many IDEs and text editors (e.g. PhpStorm, Sublime Text, Atom and Vim) have packages which will highlight any code which departs from VIP coding standards, or which has security or performance issues. Running this tool in your development environment or code editor allows you to fix the errors as you code, helping you develop to VIP best practices, and saving time during review.

PHPCS works using standards which contain sniffs. VIP uses two standards: WordPressVIPMinimum for sites that are on the WordPress.com platform, and WordPress-VIP-Go for sites on the VIP Go platform. Both of these are shipped with our VIP Coding Standards (VIPCS) package. The standards are what power our internal VIP tools used for reviewing code for the different platforms, so it is important to use the correct standard for your project. Do not attempt to use both standards together; WordPress-VIP-Go already inherits from and overrides rules from the WordPressVIPMinimum standard, so just using the correct standard is sufficient.

There are multiple ways to install VIP Coding Standards and PHPCS, but since they are PHP packages, we recommending using Composer, which is a PHP package dependency manager which you’ll need to have installed first. You can install the packages globally (so they are available for all projects), or within a project itself.

Installing VIPCS and PHPCS

Globally

  1. Run the command below in your terminal.
composer g require --dev automattic/vipwpcs dealerdirect/phpcodesniffer-composer-installer
  1. Check the path PHPCS is located at to confirm it’s available.
which phpcs
/Users/{your account name}/.composer/vendor/bin/phpcs

If it gives anything different, then you likely have installed PHPCS previously, perhaps via git or Homebrew. You may wish to uninstall these other instances.

At the project level

  1. In your terminal, navigate (cd) to the root of your project
  2. Run the command below in your terminal.
composer require --dev automattic/vipwpcs dealerdirect/phpcodesniffer-composer-installer
  1. This will add or update composer.json and composer.lock files and a vendor/ directory which you can optionally ignore in your version control.
  2. For the commands below, you’ll need to change phpcs to vendor/bin/phpcs and start.

Both approaches will install the latest release of VIPCS, the latest compatible version of PHPCS, and a compatible version of the WordPress Coding Standards (WPCS).

Note

The current VIPCS 2.x release is not compatible with WPCS 1.x; you must use WPCS 2.x (see the [README](https://github.com/Automattic/VIP-Coding-Standards#minimal-requirements) for exact minimum version).

The presence of the dealerdirect/phpcodesniffer-composer-installer Composer plugin package means that the standards will automatically be registered with PHPCS, so this task doesn’t need to be done separately. If you add further standards later on, this package will register the new standards as well.

You can check which standards you have installed by using phpcs -i. If you followed the steps above, you should have:

phpcs -i
The installed coding standards are PEAR, Zend, PSR2, MySource, Squiz, PSR1, PSR12, WordPressVIPMinimum, WordPress-VIP-Go, WordPress-VIP, WordPress, WordPress-Extra, WordPress-Docs and WordPress-Core

Note

You may see that there’s a WordPress-VIP standard in your list. You should ignore this. It is part of WPCS 1.x, but it is not used in the latest version of VIPCS, and it has been removed completely from WPCS 2.x.

Running PHPCS against your code

For WordPress.com platform:

phpcs --standard=WordPressVIPMinimum -sp --basepath=. --ignore=vendor path/to/your/code

For VIP Go platform:

phpcs --standard=WordPress-VIP-Go -sp --basepath=. --ignore=vendor path/to/your/code

This sets the appropriate standard, tells PHPCS to show the violation code for any violations, show a progress bar, cut the file paths down to be relative from the current directory, and to ignore the vendor/ directory since if you’ve followed the steps above, this will contain at a minimum the source files for VIPCS, PHPCS, WPCS, and Composer source and plugin files. The path to your code can be relative, like ..

You can also limit the command to output only errors and warnings of severity level 6 or higher, and format the output into columns:

phpcs --standard=WordPress-VIP-Go -sp --basepath=. --ignore=vendor --warning-severity=6 --error-severity=6 --report=csv /path/to/your/code/ | column -t -s, | less -S

See the PHPCS wiki for further instructions on how to use PHPCS and our page on Interpreting your PHPCS report.

Integrating PHPCS into your code editor or IDE

We recommend integrating PHPCS inside your favourite code editor or IDE to receive this feedback in real-time as you develop. Below are links to documentation on integrating PHPCS in popular editors:

PHPStorm

https://www.jetbrains.com/help/phpstorm/2019.1/using-php-code-sniffer.html

Sublime Text

https://github.com/benmatselby/sublime-phpcs
https://github.com/SublimeLinter/SublimeLinter-phpcs

Atom editor

https://atom.io/packages/linter-phpcs
https://github.com/bpearson/atom-phpcs

It’s also possible to run PHP CodeSniffer in your Continuous Integration build process, e.g. via Travis or Circle CI, which allows you to see issues reported against any pull requests and to receive reports of issues via email and other channels. If you’d like us to configure the rules to run on your VIP Go GitHub repository, then please let us know and we’ll be happy to set this up for you.

When submitting your code to VIP for the initial theme we expect the code to not trigger any PHP CodeSniffer blockers and have as few warnings as possible. We also have a list of things that we look for, not all of which are picked up by PHPCS.

How to use PHP_CodeSniffer during VIP development

PHP_CodeSniffer (aka PHPCS) is a tool that will help you write VIP approved code by ensuring it meets VIP coding standards. Running this tool in your local development environment or code editor allows you to fix the errors as you code, helping you develop to VIP best practices, and saving time during review.

PHPCS will provide messages with more information about any errors and warnings found in the codebase scanned.

When running PHPCS, ensure that the WordPress-VIP-Go standard is used. This is the standard used by VIP in all code review, including via the code analysis bot running in GitHub repositories.

Further reading

The VIP code analysis bot

PHPCS Review Feedback

Last updated: November 04, 2020