Skip to content

VIP codebase

.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

See the PHPCS documentation (or run phpcs -h) for the available command-line arguments.

Extending the root .phpcs.xml.dist file for custom themes and plugins

To enable further checks, the textdomain 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-level config -->
	<rule ref="../../.phpcs.xml.dist"/>

</ruleset>

Once the .phpcs.xml.dist file is added, it is possible to adjust for granularity of configuration using the prefixes or text_domain property.

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.

Additional reference for usage of the prefixes property can be found in the WordPress Coding Standards wiki. For those new to prefixes, this article provides a helpful explanation for the usage of prefixes in custom WordPress themes and plugins .

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. For more information, see the WordPress Coding Standards wiki for the text_domain property.

Run PHPCS

See How to run PHP_CodeSniffer.

Last updated: January 27, 2022