Skip to content

Backgrounds

How-to Guides

Technical References

VIP Codebase /

.phpcs.xml.dist

The .phpcs.xml.dist file that is in your site repo by default contains a suggested configuration for PHP_CodeSniffer (PHPCS). When running PHPCS locally, this root configuration applies to all code within the site repository.

We recommend:

  • keeping the WordPress-VIP-Go rule active
  • keeping the PHPCompatibilityWP rule active

We also recommend keeping the WordPress-Extra and WordPress-Docs rules active, though these are not required for VIP.

We also suggest you update the list of ignored paths to include third-party plugins, since this isn’t the custom code that you can fix without forking those plugins.

Getting started

From the root of your 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 lives, and type:

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, you can define textdomain and prefix configurations at the custom theme and custom plugin level. Rather than repeating the configuration values from the root .phpcs.xml.dist, we can extend from it instead.

To extend the root .phpcs.xml.dist file from the root directory, add a .phpcs.xml.dist file located in the theme or plugin that is being customized:

<?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>

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

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.

Last updated: January 14, 2022