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 VIP-Coding-Standards (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
Note
PHPCS commands on a local machine running Windows may require different formatting than the command examples shown below.
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 the local machine’s PATH.
$ ls ~/.composer/vendor/bin phpcbf phpcs
- Check PHPCS to ensure it is up to date.
$ phpcs --version PHP_CodeSniffer version 3.7.1 (stable) by Squiz (http://www.squiz.net)
Troubleshooting
If the phpcs
command does not work, the Composer bin directory on the local machine will need to be added to the PATH environment variable. On most operating systems, the phpcbf
and phpcs
files are located in the ~/.composer/vendor/bin
directory. On a local machine running Linux, the file path might be ~/.config/composer/vendor/bin
. Verify the location of the phpcbf
and phpcs
files on the user’s local machine, and modify the file path as needed when following the instructions below.
- Edit the shell profile (e.g.
~/.bash_profile
,~/.zshrc
,~/.bashrc
) and add the PATH environment variable.
The syntax (and the actual file that the shell loads on startup) will vary depending on the shell being used.
For example, in~/.bash_profile
, add the following code to the end of the file:
export PATH="$HOME/.composer/vendor/bin:$PATH"
- After adding and saving the PATH environment variable to the shell profile either
- Open a new Terminal window
- or source the shell profile in the existing Terminal window by running:
source ~/.bash_profile
.
- Run the
phpcs
command again.
Install at the project level
Considerations
- VIP applications that were created after January 2022 already contain
.phpcs.xml.dist
andcomposer.json
files. For those applications, these instructions for installation can be followed instead of the instructions below. - The current VIP-Coding-Standards (VIPCS) 2.x release requires at minimum WordPress-Coding-Standards (WPCS) 2.x. See the README for exact minimum version.
Steps to install
In the local machine’s terminal:
- Navigate (
cd
) to the root of the project. - Run the following command to add or update
composer.json
andcomposer.lock
files and avendor/
directory (thevendor/
directory can optionally be ignored in version control):
composer require --dev automattic/vipwpcs dealerdirect/phpcodesniffer-composer-installer
When PHPCS is installed locally (at the project level), it will be necessary to format the commands shown below directly referencing the executable at vendor/bin/phpcs
instead of phpcs
.
For example, this command:
phpcs -i
should instead be formatted as:
vendor/bin/
phpcs -i
Installed standards
The presence of the dealerdirect/phpcodesniffer-composer-installer
Composer plugin package automatically registers standards with PHPCS, so this task doesn’t need to be done separately. To add more standards later on, this package is able to register the new standards as well.
A list of installed standards can be returned by running the command phpcs -i
. After 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 has been removed completely from WPCS 2.x.
Running PHPCS against code
The following command example sets the appropriate standard (WordPress-VIP-Go
), tells PHPCS to show the violation code for any violations(-s
), show a progress bar (-p
), cut the file paths down to be relative from the current directory (--basepath=.
), and to ignore the vendor/
directory.
phpcs --standard=WordPress-VIP-Go -sp --basepath=. --ignore=vendor path/to/your/code
The command output can also be limited 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.
Last updated: April 03, 2023