Skip to content

.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:

  1. Navigate to the directory where the relevant .phpcs.xml.dist is located.
  2. 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: January 24, 2023