How to install PHP_CodeSniffer for WordPress.com 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.

To install VIPCS and PHPCS globally:

  1. Run composer g require --dev automattic/vipwpcs dealerdirect/phpcodesniffer-composer-installer in your terminal.
  2. Check it is accessible by using which phpcs, which should give you (on Mac OS) a path like /Users/{your account name}/.composer/vendor/bin/phpcs. If it gives anything different, then you likely already have PHPCS installed previously, perhaps via git or Homebrew. You may wish to uninstall these other instances.

To install VIPCS and PHPCS at the project level:

  1. In your terminal, navigate (cd) to the root of your project
  2. Run composer require --dev automattic/vipwpcs dealerdirect/phpcodesniffer-composer-installer in your terminal.
  3. This will add or update composer.json and composer.lock files and a vendor/ directory which you can optionally ignore in your version control.
  4. 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 that the current VIPCS 1.* release is not yet compatible with WPCS 2.*. Attempting to use VIPCS 1.* with WPCS 2.* will result in an error message of “Fatal error: require_once(): Failed opening required ‘…/WordPress/PHPCSAliases.php'”.

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:

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.*, but it is not used in the latest version of VIPCS, and it has been removed completely from WPCS 2.*.

To run 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 ..

See the PHPCS wiki for further instructions on how to use PHPCS.

You can then optionally integrate PHPCS inside your favourite editor or IDE., we have examples for a few popular ones:

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.

Ready to get started?

Drop us a note.

No matter where you are in the planning process, we’re happy to help, and we’re actual humans here on the other side of the form. 👋 We’re here to discuss your challenges and plans, evaluate your existing resources or a potential partner, or even make some initial recommendations. And, of course, we’re here to help any time you’re in the market for some robust WordPress awesomeness.