Install PHP_CodeSniffer for WordPress VIP
PHP_Codesniffer (PHPCS) can be installed by using one of two methods:
- Globally (recommended): available anywhere on your local machine
- Project level: available only when working within that project directory
Both methods will install:
- The latest release of VIPCS
- The latest compatible version of PHPCS
- The latest compatible version of the VariableAnalysis standard
- A compatible version of the WordPress Coding Standards (WPCS)
Before beginning installation, ensure that Composer itself is up to date:
composer self-update && composer global update
Install globally
- Run the command below in a terminal. This command can be run to update an existing global installation. Verbose output in the terminal will indicate what is being installed (or updated).
composer g require --dev automattic/vipwpcs dealerdirect/phpcodesniffer-composer-installer -W
- The
phpcs
command should now be in your PATH.
$ ls ~/.composer/vendor/bin phpcbf phpcs
Check PHPCS to ensure it is up to date.
$ phpcs --version PHP_CodeSniffer version 3.5.8 (stable) by Squiz (http://www.squiz.net)
- 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.
Install at the project level
- In your terminal, navigate (
cd
) to the root of your project - Run the command below in your terminal.
composer require --dev automattic/vipwpcs dealerdirect/phpcodesniffer-composer-installer
- This will add or update
composer.json
andcomposer.lock
files and avendor/
directory which you can optionally ignore in your version control. - When installed locally, using the commands below, you’ll need to change
phpcs
to directly reference the executable atvendor/bin/phpcs
.
Note
The current VIPCS 2.x release is not compatible with WPCS 1.x
.
WPCS 2.x must be used instead (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.
A list of installed standards can be returned by running the command phpcs -i
. By following the installation steps above, the returned standards should match this example:
$ 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
The WordPress-VIP
standard should not appear in the returned list. This standard 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 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
Additional guidance on Interpreting a PHPCS report is available, and further instructions on how to use PHPCS can be found in the PHPCS wiki.
Integrating PHPCS into a code editor or IDE
VIP recommends integrating PHPCS inside code editors or IDEs to receive PHPCS feedback in real-time during development.
Documentation for integrating PHPCS in a selection of 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 a Continuous Integration build process (e.g. via Travis or Circle CI), which enables issues to be reported against any pull requests and to for reports of issues to be sent via email and other channels.