WPGraphQL Coding Standards for PHP_CodeSniffer

This project is a collection of rules and sniffs for PHPCS to validate code developed for the WPGraphQL ecosystem. It uses rules from:

• WordPress Coding Standards
• Automattic VIP Coding Standards
• Slevomat Coding Standard
• PHPCompatibility & PHPCompatibilityWP

Why use these standards?

Shared coding standards are a great way to ensure consistency in your codebase. They also help to avoid common pitfalls and mistakes, which in turn helps to reduce bugs and technical debt.

These sorts of issues are particularly relevant in the WPGraphQL ecosystem, where we must create robust, performant and type-safe code that often relies on legacy PHP and WordPress code.

Additionally, by ensuring all developers are following the same guidelines and best practices, we can make it easier to collaborate on projects and ensure they stay up-to-date and compatible with WPGraphQL core and other ecosystem plugins.

While currently this ruleset only contains a collection of sniffs from other projects, we hope to add more custom sniffs in the future to help with common issues in the WPGraphQL ecosystem (e.g. ensuring properly named GraphQL types, description formatting, lazy-loaded fields, etc).

Rulesets

The project provides a superset of sniffs that the WPGraphQL community may need. If you use the WPGraphQL standard you will get all the checks.

You can use the following standard names when invoking phpcs to select the sniffs you want to use.

• WPGraphQL - complete set with all of the sniffs in the project.
  • WPGraphQL-Minimum: basic ruleset for WPGraphQL projects.
  • WPGraphQL-Strict: includes all the sniffs in the WPGraphQL-Minimum ruleset, plus additional functional sniffs to help you produce enterprise-ready code.
  • WPGraphQL-Extra: includes all the sniffs in the WPGraphQL-Strict ruleset, plus additional sniffs to keep your code consistent across your project.
  • WPGraphQL-Docs: includes sniffs for doc-blocks and inline comments.
• WPGraphQL-Core: includes all the sniffs currently used by the WPGraphQL core project. This includes the WPGraphQL-Strict and WPGraphQL-Docs ruleset, with a few sniffs disabled.

Installation

The recommended way to install this project is with Composer. Run the following command to install it into your project:

composer require --dev axepress/wp-graphql-cs

This will install the latest compatible versions of PHPCS and all the external sniffs and rulesets, so there is no need to include them in your dependencies list.

We recommend the PHP_CodeSniffer Standards Composer Installer Plugin, which handles the registration of all of the installed standards, so there is no need to set the installed_paths config value manually, for single or multiple standards.

For more information about installation and usage, see the WPCS readme.

Configuring your custom ruleset.

To quick-start your project, you can copy the example config file to your project root and rename it to .phpcs.xml.dist, then update the individual values as explained below.

The best way to use these sniffs in your project is to create a local configuration file that extends the rulesets provided by this project. When you name this file either .phpcs.xml, phpcs.xml, .phpcs.xml.dist or phpcs.xml.dist, PHP_CodeSniffer will automatically locate it as long as it is placed in the directory from which you run the CodeSniffer or in a directory above it.

In this file, you will want to configure the following:

• testVersion - The minimum PHP version you want to test against. This should be the lowest version of PHP that you want to support. While WPGraphQL officially supports PHP 7.1+, we recommend testing against PHP 7.3 (the current lowest version actively tested against) or higher.
• minimum_wp_version - The minimum WordPress version you want to test against. This should be the lowest version of WordPress that you want to support. While WPGraphQL officially supports WordPress 5.0+, we recommend testing against WordPress 5.6 (the current lowest version actively tested against) or higher.
• WordPress.WP.I18n.text_domain - The text domain used in your project. This is used by the WordPress.WP.I18n sniff to check that all translatable strings are assigned to a text domain. We recommend using the format wp-graphql-<project-name>.
• WordPress.NamingConventions.PrefixAllGlobals - The list of prefixes used in your project. This is used by the WordPress.NamingConventions.PrefixAllGlobals sniff to check that all global functions, classes, constants, and variables are prefixed.