Skip to content

Commit

Permalink
initial (public) release
Browse files Browse the repository at this point in the history
  • Loading branch information
@justlevine
justlevine committed Jun 5, 2023
0 parents commit 03f0f3c
Show file tree
Hide file tree
Showing 13 changed files with 1,137 additions and 0 deletions.
11 changes: 11 additions & 0 deletions .editorconfig
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
indent_style = tab

[*.md]
trim_trailing_whitespace = false
24 changes: 24 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
#
# Exclude files from release archives.
# This will also make them unavailable when using Composer with `--prefer-dist`.
# If you develop for VIPCS using Composer, use `--prefer-source`.
# https://blog.madewithlove.be/post/gitattributes/
#
/.editorconfig export-ignore
/.gitattributes export-ignore
/.gitignore export-ignore
/.phpcs.xml.dist export-ignore
/phpunit.xml.dist export-ignore
/.github export-ignore
/bin export-ignore
/tests export-ignore

#Auto detect text files and perform LF normalization
* text=auto

#
# The above will handle all files NOT found below
#
*.md text
*.php text
*.inc text
7 changes: 7 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
build/
vendor/
composer.lock
phpcs.xml
.phpcs.xml
phpunit.xml
phpcs.cache
12 changes: 12 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
# Changelog for WPGraphQL Coding Standards

All notable changes to this project will be documented in this file.

This projects adheres to [Semantic Versioning](https://semver.org/) and [Keep a CHANGELOG](https://keepachangelog.com/).

## [Unreleased]

_No documentation available about unreleased changes as of yet._

## [1.0.0-beta.1] - 2023-06-05
- Initial release
674 changes: 674 additions & 0 deletions LICENSE

Large diffs are not rendered by default.

56 changes: 56 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# WPGraphQL Coding Standards for [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer)

This project is a collection of rules and sniffs for PHPCS to validate code developed for the [WPGraphQL](https://github.com/wp-graphql/wp-graphql) ecosystem. It uses rules from:
- [WordPress Coding Standards](https://github.com/WordPress/WordPress-Coding-Standards)
- [Automattic VIP Coding Standards](https://github.com/Automattic/VIP-Coding-Standards)
- [Slevomat Coding Standard](https://https://github.com/slevomat/coding-standard)
- [PHPCompatibility](https://github.com/PHPCompatibility/PHPCompatibility) & [PHPCompatibilityWP](https://github.com/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`](./WPGraphQL/ruleset.xml) - complete set with all of the sniffs in the project.
- [`WPGraphQL-Minimum`](./WPGraphQL-Minimum/ruleset.xml): basic ruleset for WPGraphQL projects, including all the sniffs used by the WPGraphQL plugin itself.
- [`WPGraphQL-Strict`](./WPGraphQL-Strict/ruleset.xml): includes all the sniffs in the `WPGraphQL-Minimum` ruleset, plus additional functional sniffs to help you produce enterprise-ready code.
- [`WPGraphQL-Extra`](./WPGraphQL-Extra/ruleset.xml): includes all the sniffs in the `WPGraphQL-Strict` ruleset, plus additional formatting sniffs to keep your code looks consistent across your project.
- [`WPGraphQL-Docs`](./WPGraphQL-Docs/ruleset.xml): includes sniffs for doc-blocks and inline comments.

## Installation

The recommended way to install this project is with [Composer](https://getcomposer.org/). Run the following command to install it into your project:

```bash
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](https://github.com/Dealerdirect/phpcodesniffer-composer-installer), 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](https://github.com/WordPress/WordPress-Coding-Standards#Installation).

## Configuring your custom ruleset.

> To quick-start your project, you can copy the [example config file](./phpcs.xml.dist.example) 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](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Advanced-Usage#using-a-default-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`](./phpcs.xml.dist.example#L33) - 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](https://github.com/wp-graphql/wp-graphql/blob/develop/.github/workflows/testing-integration.yml)) or higher.
- [`minimum_supported_wp_version`](./phpcs.xml.dist.example#L43) - 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](https://github.com/wp-graphql/wp-graphql/blob/develop/.github/workflows/testing-integration.yml)) or higher.
- [`WordPress.WP.I18n.text_domain`](./phpcs.xml.dist.example#L63) - 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`](./phpcs.xml.dist.example#L57) - 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.
17 changes: 17 additions & 0 deletions WPGraphQL-Docs/ruleset.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
<?xml version="1.0"?>
<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="WPGraphQL Strict Coding Standard" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/squizlabs/PHP_CodeSniffer/master/phpcs.xsd">
<description>WPGraphQL Coding Standards for Inline Documentation and Comments</description>

<!-- The rules below are the changes from between the original sniff or parent ruleset, and what should be applied for this Standard. -->

<rule ref="Squiz.Commenting">
<severity>5</severity>
<!-- This is an uncommon pattern. -->
<exclude name="Squiz.Commenting.LongConditionClosingComment" />
<!-- This is a fairly common pattern. -->
<exclude name="Squiz.Commenting.PostStatementComment.Found" />
<!-- Not necessary if the var is typed inline. -->
<exclude name="Squiz.Commenting.VariableComment.MissingVar" />
</rule>

</ruleset>
63 changes: 63 additions & 0 deletions WPGraphQL-Extra/ruleset.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
<?xml version="1.0"?>
<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="WPGraphQL Strict Coding Standard" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/squizlabs/PHP_CodeSniffer/master/phpcs.xsd">
<description>Best practices beyond the WPGraphQL core standards</description>

<rule ref="WPGraphQL-Strict" />

<!-- The rules below are the changes from between the original sniff or parent ruleset, and what should be applied for this Standard. -->

<!-- The following rules enforce code formatting standards.-->
<rule ref="SlevomatCodingStandard.Classes.BackedEnumTypeSpacing" />
<rule ref="SlevomatCodingStandard.Classes.ClassMemberSpacing" />
<rule ref="SlevomatCodingStandard.Classes.ConstantSpacing" />
<rule ref="SlevomatCodingStandard.Classes.EmptyLinesAroundClassBraces">
<properties>
<property name="linesCountAfterOpeningBrace" value="0"/>
<property name="linesCountBeforeClosingBrace" value="0"/>
</properties>
</rule>
<rule ref="SlevomatCodingStandard.Classes.EnumCaseSpacing" />
<rule ref="SlevomatCodingStandard.Classes.MethodSpacing" />
<rule ref="SlevomatCodingStandard.Classes.ParentCallSpacing" />
<rule ref="SlevomatCodingStandard.Classes.PropertyDeclaration" />
<rule ref="SlevomatCodingStandard.Classes.PropertySpacing" />
<rule ref="SlevomatCodingStandard.Classes.TraitUseDeclaration" />
<rule ref="SlevomatCodingStandard.Classes.TraitUseSpacing">
<properties>
<property name="linesCountBeforeFirstUseWhenFirstInClass" value="0"/>
</properties>
</rule>

<rule ref="SlevomatCodingStandard.ControlStructures.DisallowTrailingMultiLineTernaryOperator" />

<rule ref="SlevomatCodingStandard.Namespaces.AlphabeticallySortedUses">
<properties>
<property name="caseSensitive" value="true"/>
</properties>
</rule>

<rule ref="SlevomatCodingStandard.Functions.ArrowFunctionDeclaration" />
<rule ref="SlevomatCodingStandard.Functions.DisallowEmptyFunction" />

<rule ref="SlevomatCodingStandard.PHP.UselessSemicolon" />

<rule ref="SlevomatCodingStandard.TypeHints.ParameterTypeHint">
<!-- WP dependencies are too loosely typed to implement this safely. -->
<exclude name="SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint" />
</rule>
<rule ref="SlevomatCodingStandard.TypeHints.ParameterTypeHintSpacing" />
<rule ref="SlevomatCodingStandard.TypeHints.PropertyTypeHint">
<!-- WP dependencies are too loosely typed to implement this safely. -->
<exclude name="SlevomatCodingStandard.TypeHints.PropertyTypeHint.MissingNativeTypeHint" />
<!-- Conflicts with Squiz.Commenting.-->
<exclude name="SlevomatCodingStandard.TypeHints.PropertyTypeHint.UselessAnnotation" />
</rule>
<rule ref="SlevomatCodingStandard.TypeHints.ReturnTypeHint">
<!-- WP dependencies are too loosely typed to implement this safely. -->
<exclude name="SlevomatCodingStandard.TypeHints.ReturnTypeHint.MissingNativeTypeHint" />
</rule>
<rule ref="SlevomatCodingStandard.TypeHints.ReturnTypeHintSpacing" />

<rule ref="SlevomatCodingStandard.Variables.UselessVariable" />

</ruleset>
58 changes: 58 additions & 0 deletions WPGraphQL-Minimum/ruleset.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
<?xml version="1.0"?>
<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="WPGraphQL Minimum Coding Standard" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/squizlabs/PHP_CodeSniffer/master/phpcs.xsd">
<description>WPGraphQL Minimum Coding Standard</description>

<!-- The rules below are the changes from between the original sniff or parent ruleset, and what should be applied for this Standard. -->

<rule ref="PHPCompatibilityWP">
<include-pattern>*\.php$</include-pattern>
</rule>

<!-- Load WordPress VIP Go standards - for use with projects on the (newer) VIP Go platform. -->
<rule ref="WordPress-VIP-Go" />

<rule ref="Squiz.Functions.MultiLineFunctionDeclaration.SpaceAfterFunction"/>

<rule ref="WordPress-Core">
<exclude name="Generic.Arrays.DisallowShortArraySyntax"/>

<!-- Should probably not be added back -->
<exclude name="PHPCompatibility.Keywords.ForbiddenNamesAsDeclared.objectFound"/>

<!-- Added back in WPGraphQL-Strict -->
<exclude name="Squiz.PHP.DisallowMultipleAssignments.FoundInControlStructure"/>
<exclude name="PEAR.Functions.FunctionCallSignature.ContentAfterOpenBracket"/>
<exclude name="PEAR.Functions.FunctionCallSignature.CloseBracketLine"/>
<exclude name="PEAR.Functions.FunctionCallSignature.MultipleArguments"/>
</rule>

<!-- Load WordPress Coding standards -->
<rule ref="WordPress">
<exclude name="WordPress.NamingConventions.ValidVariableName"/>
<exclude name="WordPress.NamingConventions.ValidHookName.UseUnderscores"/>
<exclude name="WordPress.Files.FileName"/>

<!-- Definitely should not be added back -->
<exclude name="WordPress.PHP.DisallowShortTernary.Found"/>
<exclude name="WordPress.CodeAnalysis.AssignmentInCondition.Found"/>

<!-- Added back in WPGraphQL-Strict -->
<exclude name="WordPress.WP.I18n.MissingTranslatorsComment"/>
<exclude name="WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid"/>
<exclude name="WordPress.DateTime.RestrictedFunctions.date_date"/>
</rule>

<!-- Tests for inline documentation of code -->
<rule ref="WordPress-Docs">
<exclude name="Generic.Commenting.DocComment.MissingShort"/>

<!-- Added back in WPGraphQL-Docs -->
<exclude name="Squiz.Commenting"/>
</rule>

<!-- Enforce short array syntax -->
<rule ref="Generic.Arrays.DisallowLongArraySyntax"/>

<!-- Enforce FQCN in comments -->
<rule ref="SlevomatCodingStandard.Namespaces.FullyQualifiedClassNameInAnnotation"/>
</ruleset>
90 changes: 90 additions & 0 deletions WPGraphQL-Strict/ruleset.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
<?xml version="1.0"?>
<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="WPGraphQL Strict Coding Standard" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/squizlabs/PHP_CodeSniffer/master/phpcs.xsd">
<description>WPGraphQL Strict Coding Standard</description>

<rule ref="WPGraphQL-Minimum" />

<!-- The rules below are the changes from between the original sniff or parent ruleset, and what should be applied for this Standard. -->

<!-- These are disabled in WPGraphQL core but should be reenabled. -->
<rule ref="WordPress.WhiteSpace.ControlStructureSpacing">
<properties>
<property name="blank_line_check" value="true"/>
</properties>
</rule>
<rule ref="Squiz.PHP.DisallowMultipleAssignments.FoundInControlStructure">
<severity>5</severity>
</rule>
<rule ref="PEAR.Functions.FunctionCallSignature.ContentAfterOpenBracket">
<severity>5</severity>
</rule>
<rule ref="PEAR.Functions.FunctionCallSignature.CloseBracketLine">
<severity>5</severity>
</rule>
<rule ref="PEAR.Functions.FunctionCallSignature.MultipleArguments">
<severity>5</severity>
</rule>
<rule ref="WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid">
<severity>5</severity>
</rule>
<rule ref="WordPress.DateTime.RestrictedFunctions.date_date">
<severity>5</severity>
</rule>
<rule ref="WordPress.WP.I18n.MissingTranslatorsComment">
<severity>5</severity>
</rule>

<!-- Additional commenting sniffs are in WPGraphQL-Docs -->
<rule ref="Squiz.Commenting.FunctionComment">
<properties>
<property name="skipIfInheritdoc" value="true" />
</properties>
</rule>

<!-- Slevomat rules - subject to review -->
<rule ref="SlevomatCodingStandard.Arrays">
<!-- Conflicts with WPCS -->
<exclude name="SlevomatCodingStandard.Arrays.SingleLineArrayWhitespace"/>
<!-- Semantic sorting is a valid pattern -->
<exclude name="SlevomatCodingStandard.Arrays.AlphabeticallySortedByKeys"/>
</rule>

<rule ref="SlevomatCodingStandard.Classes.ModernClassNameReference">
<properties>
<!-- Doesn't use PHPCompatibility-->
<property name="enableOnObjects" value="false"/>
</properties>
</rule>
<rule ref="SlevomatCodingStandard.Classes.RequireSelfReference" />
<rule ref="SlevomatCodingStandard.Classes.DisallowConstructorPropertyPromotion" />
<rule ref="SlevomatCodingStandard.Classes.DisallowLateStaticBindingForConstants" />
<rule ref="SlevomatCodingStandard.Classes.DisallowMultiConstantDefinition" />
<rule ref="SlevomatCodingStandard.Classes.DisallowMultiPropertyDefinition" />
<rule ref="SlevomatCodingStandard.Classes.DisallowStringExpressionPropertyFetch" />
<rule ref="SlevomatCodingStandard.Classes.ClassConstantVisibility" />
<rule ref="SlevomatCodingStandard.Classes.UselessLateStaticBinding" />

<rule ref="SlevomatCodingStandard.ControlStructures.UselessTernaryOperator" />

<rule ref="SlevomatCodingStandard.Exceptions.DeadCatch" />
<rule ref="SlevomatCodingStandard.Exceptions.DisallowNonCapturingCatch" />
<rule ref="SlevomatCodingStandard.Exceptions.ReferenceThrowableOnly" />

<rule ref="SlevomatCodingStandard.Functions.StaticClosure" />
<rule ref="SlevomatCodingStandard.Functions.UnusedInheritedVariablePassedToClosure" />
<rule ref="SlevomatCodingStandard.Functions.UselessParameterDefaultValue" />

<rule ref="SlevomatCodingStandard.Namespaces.UnusedUses" />
<rule ref="SlevomatCodingStandard.Namespaces.UseDoesNotStartWithBackslash" />

<rule ref="SlevomatCodingStandard.PHP.OptimizedFunctionsWithoutUnpacking" />
<rule ref="SlevomatCodingStandard.PHP.TypeCast" />

<rule ref="SlevomatCodingStandard.Variables.DuplicateAssignmentToVariable" />
<rule ref="SlevomatCodingStandard.Variables.UnusedVariable" >
<properties>
<property name="ignoreUnusedValuesWhenOnlyKeysAreUsedInForeach" value="true" />
</properties>
</rule>

</ruleset>
9 changes: 9 additions & 0 deletions WPGraphQL/ruleset.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
<?xml version="1.0"?>
<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="WPGraphQL Strict Coding Standard" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/squizlabs/PHP_CodeSniffer/master/phpcs.xsd">
<description>WPGraphQL Coding Standards</description>

<!-- Includes WPGrapQL-Minimum and WPGraphQL-Strict-->
<rule ref="WPGraphQL-Extra" />
<rule ref="WPGraphQL-Docs" />

</ruleset>
Loading

0 comments on commit 03f0f3c

Please sign in to comment.