.phpcs.xml.dist
The .phpcs.xml.dist file is in a VIP site repo by default. It contains a suggested configuration for PHP_CodeSniffer (PHPCS). When running PHPCS locally, this root configuration applies to all code within the site repository.
VIP recommends:
- keeping the
WordPress-VIP-Go
rule active - keeping the
PHPCompatibilityWP
rule active
It is also recommended that the WordPress-Extra
and WordPress-Docs
rules remain active, though these are not required for VIP.
The list of ignored paths should include third-party plugins, as the custom code in third-party plugins cannot be modified without forking those plugins.
Getting started
From the root of a site repository, run:
composer install
This will install PHP_CodeSniffer and register the below standards:
To run PHPCS:
- Navigate to the directory where the relevant .phpcs.xml.dist is located.
- In the terminal run:
vendor/bin/phpcs
Run phpcs -h
to see the available command-line arguments.
Extending the root .phpcs.xml.dist
file for custom themes and plugins
To enable further checks, the text domain and prefix configurations can be defined at the custom theme and custom plugin level. Rather than repeating the configuration values from the root .phpcs.xml.dist, it is possible to extend the .phpcs.xml.dist file from the root directory instead.
To extend the root .phpcs.xml.dist file from the root directory, add a .phpcs.xml.dist file into the directory of the theme or plugin that is being customized. An example .phpcs.xml.dist file:
<?xml version="1.0"?>
<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="PHPCS config" xsi:noNamespaceSchemaLocation="../../vendor/squizlabs/php_codesniffer/phpcs.xsd">
<!-- Extend the repo root config -->
<rule ref="../../.phpcs.xml.dist"/>
</ruleset>
Once the .phpcs.xml.dist file is added, it is possible to adjust for the granularity of configuration using the prefixes
or text_domain
properties.
Using the prefixes
property
The WordPress.NamingConventions.PrefixAllGlobals
sniff can verify an input of one or more prefixes that would be considered valid in the appropriate places. Add the following rule alongside the existing previous rule in the custom theme or plugin’s .phpcs.xml.dist:
<!-- For help in understanding this text_domain property:
https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/wiki/Customizable-sniff-properties#internationalization-setting-your-text-domain -->
<rule ref="WordPress.NamingConventions.PrefixAllGlobals">
<properties>
<property name="prefixes" type="array">
<element value="your_theme_or_plugin_prefix"/> <!-- Change this value to your theme or plugin prefix. -->
</property>
</properties>
</rule>
If this property is not set, these checks will be skipped.
Using the text_domain
property
The WordPress.WP.I18n
sniff can verify if all internationalization (i18n) function calls contain a $text_domain
argument that matches a particular string. This string should match the theme or plugin slug. Add the following rule alongside the existing previous rule in the custom theme or plugin’s .phpcs.xml.dist:
<rule ref="WordPress.WP.I18n">
<properties>
<property name="text_domain" type="array">
<element value="your_theme_or_plugin_slug"/> <!-- Change this value to your theme or plugin slug. -->
</property>
</properties>
</rule>
If this property is not set, these checks will be skipped.
Last updated: April 03, 2023