PHP_CodeSniffer rules (sniffs) to enforce WordPress coding conventions
- Project history
- How to use
- Running your code through WPCS automatically using CI tools
- Fixing errors or whitelisting them
This project is a collection of PHP_CodeSniffer rules (sniffs) to validate code developed for WordPress. It ensures code quality and adherence to coding conventions, especially the official WordPress Coding Standards.
- In April 2009 original project from Urban Giraffe was published.
- In May 2011 the project was forked on GitHub by Chris Adams.
- In April 2012 XWP started to dedicate resources to develop and lead the creation of the sniffs and rulesets for
WordPress-VIP(WordPress.com VIP), and
- In 2015, J.D. Grimes began significant contributions, along with maintenance from Gary Jones.
- In 2016, Juliette Reinders Folmer began contributing heavily, adding more commits in a year than anyone else in 5 years previous since the project's inception.
The WordPress Coding Standards require PHP 5.3 or higher and PHP_CodeSniffer version 2.9.0 or higher. As of version 0.13.0, the WordPress Coding Standards are compatible with PHPCS 3.0.2+. In that case, the minimum PHP requirement is PHP 5.4.
Standards can be installed with the Composer dependency manager:
composer create-project wp-coding-standards/wpcs --no-dev
Running this command will:
- Install WordPress standards into
- Install PHP_CodeSniffer.
- Register WordPress standards in PHP_CodeSniffer configuration.
phpcscommand available from
For the convenience of using
phpcs as a global command, you may want to add the path to the
wpcs/vendor/scripts (PHPCS 2.x) and/or
wpcs/vendor/bin (PHPCS 3.x) directories to a
PATH environment variable for your operating system.
When installing the WordPress Coding Standards as a dependency in a larger project, the above mentioned step 3 will not be executed automatically.
There are two actively maintained Composer plugins which can handle the registration of standards with PHP_CodeSniffer for you:
It is strongly suggested to
require one of these plugins in your project to handle the registration of external standards with PHPCS for you.
Install PHP_CodeSniffer by following its installation instructions (via Composer, Phar file, PEAR, or Git checkout).
Clone the WordPress standards repository:
git clone -b master https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards.git wpcs
Add its path to the PHP_CodeSniffer configuration:
phpcs --config-set installed_paths /path/to/wpcs
Pro-tip: Alternatively, you can tell PHP_CodeSniffer the path to the WordPress standards by adding the following snippet to your custom ruleset:
<config name="installed_paths" value="/path/to/wpcs" />
cd ~/projects git clone https://github.com/squizlabs/PHP_CodeSniffer.git phpcs git clone -b master https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards.git wpcs cd phpcs #PHPCS 2.x ./scripts/phpcs --config-set installed_paths ../wpcs #PHPCS 3.x ./bin/phpcs --config-set installed_paths ../wpcs
And then add the
~/projects/phpcs/scripts (PHPCS 2.x) or
~/projects/phpcs/bin (PHPCS 3.x) directory to your
PATH environment variable via your
You should then see
WordPress-Core et al listed when you run
The project encompasses a super-set of the sniffs that the WordPress community may need. If you use the
WordPress standard you will get all the checks. Some of them might be unnecessary for your environment, for example, those specific to WordPress.com VIP coding requirements.
You can use the following as standard names when invoking
phpcs to select sniffs, fitting your needs:
WordPress- complete set with all of the sniffs in the project
WordPress-Core- main ruleset for WordPress core coding standards
WordPress-Docs- additional ruleset for WordPress inline documentation standards
WordPress-Extra- extended ruleset for recommended best practices, not sufficiently covered in the WordPress core coding standards
WordPress-VIP- extended ruleset for WordPress.com VIP coding requirements
If you need to further customize the selection of sniffs for your project - you can create a custom ruleset file. When you name this file either
phpcs.xml.dist, PHP_CodeSniffer will automatically locate it as long as it is placed in the directory from which you run the CodeSniffer or in a directory above it. If you follow these naming conventions you don't have to supply a
--standard arg. For more info, read about using a default configuration file. See also provided
phpcs.xml.dist.sample file and fully annotated example in the PHP_CodeSniffer documentation.
The WordPress Coding Standard contains a number of sniffs which are configurable. This means that you can turn parts of the sniff on or off, or change the behaviour by setting a property for the sniff in your custom
You can find a complete list of all the properties you can change in the wiki.
The PHPCompatibility ruleset comes highly recommended. The PHPCompatibility sniffs are designed to analyse your code for cross-PHP version compatibility. Install it as a separate ruleset and either run it separately against your code or add it to your custom ruleset.
Whichever way you run it, do make sure you set the
testVersion to run the sniffs against. The
testVersion determines for which PHP versions you will receive compatibility information. The recommended setting for this at this moment is
5.2-7.1 to support the same PHP versions as WordPress Core supports.
For more information about setting the
phpcs command line tool on a given file or directory, for example:
phpcs --standard=WordPress wp-load.php
Will result in following output:
-------------------------------------------------------------------------------- FOUND 10 ERRORS AND 5 WARNINGS AFFECTING 8 LINES -------------------------------------------------------------------------------- 24 | WARNING | [ ] error_reporting() can lead to full path disclosure. 24 | WARNING | [ ] error_reporting() found. Changing configuration at runtime | | is rarely necessary. 34 | ERROR | [x] Expected 1 spaces before closing bracket; 0 found 39 | WARNING | [ ] Silencing errors is discouraged 39 | WARNING | [ ] Silencing errors is discouraged 46 | ERROR | [ ] Inline comments must end in full-stops, exclamation marks, | | or question marks 46 | ERROR | [x] There must be no blank line following an inline comment 63 | WARNING | [ ] Detected access of super global var $_SERVER, probably | | needs manual inspection. 63 | ERROR | [ ] Detected usage of a non-validated input variable: $_SERVER 63 | ERROR | [ ] Missing wp_unslash() before sanitization. 63 | ERROR | [ ] Detected usage of a non-sanitized input variable: $_SERVER 74 | ERROR | [ ] Inline comments must end in full-stops, exclamation marks, | | or question marks 90 | ERROR | [x] String "Create a Configuration File" does not require | | double quotes; use single quotes instead 92 | ERROR | [ ] Expected next thing to be an escaping function (see Codex | | for 'Data Validation'), not '$die' 92 | ERROR | [ ] Expected next thing to be an escaping function (see Codex | | for 'Data Validation'), not '__' -------------------------------------------------------------------------------- PHPCBF CAN FIX THE 3 MARKED SNIFF VIOLATIONS AUTOMATICALLY --------------------------------------------------------------------------------
- PhpStorm : Please see "PHP Code Sniffer with WordPress Coding Standards Integration" in the PhpStorm documentation.
- Sublime Text : Please see "Setting up WPCS to work in Sublime Text" in the wiki.
- Atom: Please see "Setting up WPCS to work in Atom" in the wiki.
- Visual Studio: Please see "Setting up PHP CodeSniffer in Visual Studio Code", a tutorial by Tom McFarlin.
- Eclipse with XAMPP: Please see "Setting up WPCS when using Eclipse with XAMPP" in the wiki.
To integrate PHPCS with WPCS with Travis CI, you'll need to install both
before_install and add the run command to the
If your project uses Composer, the typical instructions might be different.
If you use a matrix setup in Travis to test your code against different PHP and/or WordPress versions, you don't need to run PHPCS on each variant of the matrix as the results will be same. You can set an environment variable in the Travis matrix to only run the sniffs against one setup in the matrix.
language: php matrix: include: # Arbitrary PHP version to run the sniffs against. - php: '7.0' env: SNIFF=1 before_install: - if [[ "$SNIFF" == "1" ]]; then export PHPCS_DIR=/tmp/phpcs; fi - if [[ "$SNIFF" == "1" ]]; then export SNIFFS_DIR=/tmp/sniffs; fi # Install PHP_CodeSniffer. - if [[ "$SNIFF" == "1" ]]; then git clone -b master --depth 1 https://github.com/squizlabs/PHP_CodeSniffer.git $PHPCS_DIR; fi # Install WordPress Coding Standards. - if [[ "$SNIFF" == "1" ]]; then git clone -b master --depth 1 https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards.git $SNIFFS_DIR; fi # Set install path for WordPress Coding Standards. - if [[ "$SNIFF" == "1" ]]; then $PHPCS_DIR/bin/phpcs --config-set installed_paths $SNIFFS_DIR; fi # After CodeSniffer install you should refresh your path. - if [[ "$SNIFF" == "1" ]]; then phpenv rehash; fi script: # Run against WordPress Coding Standards. # If you use a custom ruleset, change `--standard=WordPress` to point to your ruleset file, # for example: `--standard=wpcs.xml`. # You can use any of the normal PHPCS command line arguments in the command: # https://github.com/squizlabs/PHP_CodeSniffer/wiki/Usage - if [[ "$SNIFF" == "1" ]]; then $PHPCS_DIR/bin/phpcs -p . --standard=WordPress; fi
You can find information on how to deal with some of the more frequent issues in the wiki.
See LICENSE (MIT).