.phpcs.xml.dist

A .phpcs.xml.dist file exists by default in all wpcomvip GitHub repositories that were created for WordPress applications since January 2022. The file contains a suggested configuration for PHP_CodeSniffer (PHPCS). When running PHPCS locally, this root configuration applies to all code within the application 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

To run PHPCS locally using the configuration of .phpcs.xml.dist, a clone of an application’s wpcomvip GitHub repository must exist locally.

1. Obtain the URL for the application’s wpcomvip GitHub repository (e.g., https://github.com/wpcomvip/example-repo). This can be found in the Overview panel of the application’s VIP Dashboard.
2. Navigate to the application’s wpcomvip GitHub repository.
3. Follow GitHub’s instructions for cloning a repository to a local machine.
   For most users, this step can be completed with a git command.
   • In this git clone command example, a repository found at the URL https://github.com/wpcomvip/example-repo is cloned to a local machine:
     git clone git@github.com:wpcomvip/example-repo.git

4. From the root of the cloned application repository, run the command:

composer install

This will install PHP_CodeSniffer and register the below standards:

• VIP Coding Standards
• WordPress Coding Standards
• PHPCompatibilityWP Standard
• Extra supporting standards that VIPCS and WordPressCS use.

Run PHPCS

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 review 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. Example .phpcs.xml.dist file content:

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