- Introduction
- Minimum Requirements
- Installation
- Rulesets
- How to use
- Running your code through WordPressCS automatically using Continuous Integration tools
- Fi xing errors or ignoring them
- Contributing
- Funding
- License
This project is a collection ofPHP_CodeSnifferrules (sniffs) to validate code developed for WordPress. It ensures code quality and adherence to coding conventions, especially the officialWordPress Coding Standards.
This project needs funding.Find out how you can help.
The WordPress Coding Standards package requires:
For the best results, it is recommended to also ensure the following additional PHP extensions are enabled:
As ofWordPressCS 3.0.0,installation via Composer using the below instructions is the only supported type of installation.
Composerwill automatically install the project dependencies and register the rulesets from WordPressCS and other external standards with PHP_CodeSniffer using theComposer PHPCS plugin.
If you are upgrading from an older WordPressCS version to version 3.0.0, please read theUpgrade guide for ruleset maintainers and end-usersfirst!
Run the following from the root of your project:
composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installertrue
composer require --dev wp-coding-standards/wpcs:"^3.0"Alternatively, you may want to install this standard globally:
composer global config allow-plugins.dealerdirect/phpcodesniffer-composer-installertrue
composer global require --dev wp-coding-standards/wpcs:"^3.0"If you installed WordPressCS using either of the above commands, you can upgrade to a newer version as follows:
#Project local install
composer update wp-coding-standards/wpcs --with-dependencies
#Global install
composer global update wp-coding-standards/wpcs --with-dependenciesOnce you have installed WordPressCS using either of the above commands, use it as follows:
#Project local install
vendor/bin/phpcs -ps.--standard=WordPress
#Global install
%USER_DIRECTORY%/Composer/vendor/bin/phpcs -ps.--standard=WordPressPro-tip:For the convenience of using
phpcsas a global command, use theGlobal installmethod and add the path to the%USER_DIRECTORY%/Composer/vendor/bindirectory to thePATHenvironment variable for your operating system.
The project encompasses a super-set of the sniffs that the WordPress community may need. If you use theWordPressstandard you will get all the checks.
You can use the following as standard names when invokingphpcsto select sniffs, fitting your needs:
WordPress- complete set with all of the sniffs in the projectWordPress-Core- main ruleset forWordPress core coding standardsWordPress-Docs- additional ruleset forWordPress inline documentation standardsWordPress-Extra- extended ruleset with recommended best practices, not sufficiently covered in the WordPress core coding standards- includes
WordPress-Core
- includes
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,phpcs.xml,.phpcs.xml.distorphpcs.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--standardCLI argument.
For more info, read aboutusing a default configuration file.See also the provided WordPressCSphpcs.xml.dist.samplefile and thefully annotated example rulesetin 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[.]phpcs.xml[.dist]file.
You can find a complete list of all the properties you can change for the WordPressCS sniffs in thewiki.
WordPressCS also uses sniffs from PHPCSExtra and from PHP_CodeSniffer itself. TheREADME for PHPCSExtracontains information on the properties which can be set for the sniff from PHPCSExtra. Information on custom properties which can be set for sniffs from PHP_CodeSniffer can be found in thePHP_CodeSniffer wiki.
ThePHPCompatibilityruleset and its subsetPHPCompatibilityWPcome highly recommended. ThePHPCompatibilitysniffs are designed to analyse your code for cross-version PHP compatibility.
ThePHPCompatibilityWPruleset is based on PHPCompatibility, but specifically crafted to prevent false positives for projects which expect to run within the context of WordPress, i.e. core, plugins and themes.
Install either as a separate ruleset and run it separately against your code or add it to your custom ruleset, like so:
<configname="testVersion"value="7.0-"/>
<ruleref="PHPCompatibilityWP">
<include-pattern>*\.php$</include-pattern>
</rule>Whichever way you run it, do make sure you set thetestVersionto run the sniffs against. ThetestVersiondetermines for which PHP versions you will receive compatibility information. The recommended setting for this at this moment is7.0-to support the same PHP versions as WordPress Core supports.
For more information about setting thetestVersion,see:
- PHPCompatibility: Sniffing your code for compatibility with specific PHP version(s)
- PHPCompatibility: Using a custom ruleset
For some additional checks around (undefined/unused) variables, theVariableAnalysisstandard is a handy addition.
For those projects which deploy to the WordPress VIP platform, it is recommended to also use theofficial WordPress VIP coding standardsruleset.
Run thephpcscommand line tool on a given file or directory, for example:
vendor/bin/phpcs --standard=WordPress wp-load.phpWill result in following output:
--------------------------------------------------------------------------------
FOUND 6 ERRORS AND 4 WARNINGS AFFECTING 5 LINES
--------------------------------------------------------------------------------
36 | WARNING | error_reporting() can lead to full path disclosure.
36 | WARNING | error_reporting() found. Changing configuration values at
| | runtime is strongly discouraged.
52 | WARNING | Silencing errors is strongly discouraged. Use proper error
| | checking instead. Found: @file_exists( dirname(...
52 | WARNING | Silencing errors is strongly discouraged. Use proper error
| | checking instead. Found: @file_exists( dirname(...
75 | ERROR | Overriding WordPress globals is prohibited. Found assignment
| | to $path
78 | ERROR | Detected usage of a possibly undefined superglobal array
| | index: $_SERVER['REQUEST_URI']. Use isset() or empty() to
| | check the index exists before using it
78 | ERROR | $_SERVER['REQUEST_URI'] not unslashed before sanitization. Use
| | wp_unslash() or similar
78 | ERROR | Detected usage of a non-sanitized input variable:
| | $_SERVER['REQUEST_URI']
104 | ERROR | All output should be run through an escaping function (see the
| | Security sections in the WordPress Developer Handbooks), found
| | '$die'.
104 | ERROR | All output should be run through an escaping function (see the
| | Security sections in the WordPress Developer Handbooks), found
| | '__'.
--------------------------------------------------------------------------------
Thewikicontains links to various in- and external tutorials about setting up WordPressCS to work in your IDE.
You can find information on how to deal with some of the more frequent issues in thewiki.
Since version 1.2.0, WordPressCS has a special sniff categoryUtils.
This sniff category contains some tools which, generally speaking, will only be needed to be run once over a codebase and for which the fixers can be consideredrisky,i.e. very careful review by a developer is needed before accepting the fixes made by these sniffs.
The sniffs in this category are disabled by default and can only be activated by adding some properties for each sniff via a custom ruleset.
At this moment, WordPressCS offer the following tools:
WordPress.Utils.I18nTextDomainFixer- This sniff can replace the text domain used in a code-base. The sniff will fix the text domains in both I18n function calls as well as in a plugin/theme header. Passing the following properties will activate the sniff:old_text_domain:an array with one or more (old) text domain names which need to be replaced;new_text_domain:the correct (new) text domain as a string.
SeeCONTRIBUTING,including information aboutunit testingthe standard.
If you want to sponsor the work on WordPressCS, you can do so by donating to thePHP_CodeSniffer Open Collective.
SeeLICENSE(MIT).
