WordPress Coding Standards

You can customize your coding standard selection by creating a configuration file in your project root. If you name the file one of the following, PHP_CodeSniffer will automatically detect it without needing the --standard CLI argument:

• .phpcs.xml
• phpcs.xml
• .phpcs.xml.dist
• phpcs.xml.dist

To install WordPress Coding Standards globally on your system, use the following commands. This allows you to use the standards across multiple projects.

composer global config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
composer global require --dev wp-coding-standards/wpcs:"^3.0"

WordPressCS can be automated within CI pipelines. Documentation for specific platforms is available on the project wiki:

• Running in GitHub Actions
• Running in Travis

To use WordPress Coding Standards, ensure your environment meets the following requirements:

Required:

• PHP 7.2 or higher
• PHP extensions: Filter, libxml, Tokenizer, and XMLReader
• Composer

Recommended:

• PHP extensions: iconv and Multibyte String (mbstring)

To install WordPress Coding Standards as a development dependency within a specific project, run the following commands from your project root. This requires the dealerdirect/phpcodesniffer-composer-installer plugin to be enabled via Composer configuration.

composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
composer require --dev wp-coding-standards/wpcs:"^3.0"

To check for cross-version PHP compatibility within a WordPress context, add the PHPCompatibilityWP rule to your custom [.]phpcs.xml[.dist] file. It is highly recommended to set the testVersion property to 7.2- to support the last three WordPress releases.

<config name="testVersion" value="7.2-"/>
<rule ref="PHPCompatibilityWP">
    <include-pattern>*.php</include-pattern>
</rule>

The WordPress.Utils.I18nTextDomainFixer is a tool within the Utils sniff category designed to replace text domains across a codebase, including I18n function calls and plugin/theme headers.

Note: Sniffs in the Utils category are disabled by default and are considered risky. They must be activated via a custom ruleset by providing specific properties.

To activate this sniff, include the following properties in your custom ruleset:

• old_text_domain: An array containing one or more old text domain names to be replaced.
• new_text_domain: A string representing the new, correct text domain.

WordPressCS provides several standard names to select specific levels of scrutiny when invoking phpcs:

• WordPress: The complete set containing all sniffs.
• WordPress-Core: The main ruleset for WordPress core coding standards.
• WordPress-Docs: Additional ruleset for WordPress inline documentation standards.
• WordPress-Extra: An extended ruleset including WordPress-Core plus recommended best practices not covered by core standards.

You can run the phpcs command line tool against specific files or directories using the WordPress standard. If you installed WordPressCS locally via Composer, use the path to the vendor binary.

Example command:

vendor/bin/phpcs --standard=WordPress wp-load.php