Skip to content

How-to Guides

Technical References

Code Review /

Install PHP_CodeSniffer for WordPress VIP

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

We highly recommend using PHPCS locally, and then also review the VIP code review bot’s comments (if any) on your pull request. Address any issues, and minimize or suppress any remaining errors or warnings, before submitting your code changes to VIP for a review.

PHPCS works using standards which contain sniffs. VIP uses the WordPress-VIP-Go standard, which inherits from and overrides rules from the parent WordPressVIPMinimum standard. Both of these standards are shipped with our VIP Coding Standards (VIPCS) package. Please use the correct standard for your project (WordPress-VIP-Go) and do not attempt to use both standards together.

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 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 or Updating VIPCS and PHPCS with Composer

Choose one or the other: globally (available anywhere on your local machine), or project level (available only when you’re in that project directory.

Ensure Composer itself is up to date:

composer self-update && composer global update
  1. Run the command below in your terminal. You can run this command to update an existing global installation. You should see verbose output noting what is being installed (or updated).
composer g require --dev automattic/vipwpcs dealerdirect/phpcodesniffer-composer-installer -W
  1. The phpcs command should now be in your PATH. Check PHPCS to ensure it is up to date.
$ ls ~/.composer/vendor/bin
phpcbf	phpcs
$ phpcs --version
PHP_CodeSniffer version 3.5.8 (stable) by Squiz (http://www.squiz.net)

3. If the phpcs command did not work, but the two files shown above are in the ~/.composer/vendor/bin directory, then you’ll need to add the Composer bin directory to your PATH environment variable so that the shell can locate the new commands, and then try again.

Edit your shell profile (e.g. ~/.bash_profile, ~/.zshrc) and add the necessary line, for example in ~/.bash_profile, add at the end of the file:

export PATH="$HOME/.composer/vendor/bin:$PATH"

Note that the syntax (and the actual file your shell loads on startup) varies depending on the shell you’re using.

Then either open a new Terminal window, or source the profile, source ~/.bash_profile and then try the phpcs command again.

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. When installed locally, using the commands below, you’ll need to change phpcs to directly reference the executable at vendor/bin/phpcs.

What is installed

Both approaches will install the following:

Note

The current VIPCS 2.x release is not compatible with WPCS 1.x; you must use WPCS 2.x (see the README for exact minimum version).

The presence of the dealerdirect/phpcodesniffer-composer-installer Composer plugin package means 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, WordPress-Extra, WordPress-Docs and WordPress-Core

Note

You should not see a WordPress-VIP standard in your list. It has been deprecated, is not used in the latest version of VIPCS, and it has been removed completely from WPCS 2.x.

Running PHPCS against your code

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 (if you’ve followed the local install 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 favorite 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:

VS Code

Multiple plugins are available.

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.

Last updated: February 11, 2021