v3.0.0

What's Changed

• Update authors in composer.json by @jaymcp in #159
• Introduce more comprehensive docblock coverage by @jaymcp in #168
• Add support for Enums to filename sniff by @jaymcp in #170
• Add new Sniff to restrict line length in docblocks by @jaymcp in #171
• Implement new rules for further conformity checking by @jaymcp in #169
• Add Sniff to ensure usage of Stringable interface by @jaymcp in #172
• Implement Sniff to ensure a blank line before an object's closing brace by @jaymcp in #173
• Implement Sniff to ensure a blank line after an object's opening brace by @jaymcp in #174
• Add sniff to ban heredocs. by @jaymcp in #175
• Add Sniff to enforce shorthand array syntax by @jaymcp in #177
• Run tests against PHP 8.4 in CI by @jaymcp in #178
• Add new Sniff to check declare statements by @jaymcp in #179
• Update line length sniff to disregard long parameter type hints by @jaymcp in #180
• Update line length sniff to disregard lines containing specific prefixes by @jaymcp in #181
• Add several new Sniffs from the Universal standard by @jaymcp in #182
• Move all documentation Sniffs to a separate standard by @jaymcp in #183
• Bump minimum PHP version to 8.2; set PHPStan to level 8 by @jaymcp in #184
• Exclude increment/decrement Sniff that conflicts with our standard by @jaymcp in #186
• Remove tag restrictions from class comments by @jaymcp in #187
• Move DocCommentLineLength Sniff to Docs ruleset by @jaymcp in #188
• Fix stringable sniff to account for namespaces by @jaymcp in #189
• Enable PHPCS scanning of test directories by @jaymcp in #191
• Replace Squiz.Commenting.FunctionComment with new Sniff by @jaymcp in #192

Full Changelog: v2.0.1...v3.0.0

Upgrading

The ruleset PHP minimum version has been bumped to 7.2, and should work without issue on that version and above.
The ruleset will default to analysing against PHP 8.2 and above by default.
To change your project's PHP version requirement, set this config in your PHPCS config file:

<config name="testVersion" value="8.0-" />

The terminal output now has colours! 🎉

File exclusion changes

The list of excluded file patterns has been updated:

• Tests directories are no longer exempt
• Built asset files from Build Tools are now exempt (*/dist/*.asset.php)
• Built asset files from WP Scripts are now exempt (*/build/*.asset.php)

For projects that implement PHP tests, you are likely to encounter lots of new errors from files that have not previously been analysed.

Rule changes

There are many individual rule changes, so they have been broken up into code and documentation sections.
"Documentation", in this case, refers to code documentation - comments, docblocks, etc.., and will still only analyse PHP files.

Code

Several changes have been made to our custom sniffs, and a few new custom sniffs have been added:

• The presence of a heredoc will now trigger an error
  Sniff: BigBite.PHP.Heredoc
  Use string interpolation or sprintf instead.
• A blank line between an object declaration and the first content within is now enforced
  Sniff: BigBite.Objects.NewLineAfterOpeningBrace
  This sniff includes a fixer.
• A blank line between the last content within an object declaration and the object's closing brace is now enforced
  Sniff: BigBite.Objects.NewLineBeforeClosingBrace
  This sniff includes a fixer.
• When using PHP 8.0 or higher, classes that implement the __toString method must now implement the Stringable interface
  Sniff: BigBite.Classes.Stringable
  This sniff includes a fixer.
• The format of declare statements, where present, is now enforced
  Sniff: BigBite.Files.DeclareStatement
  This sniff includes a fixer, and enforces the following format:
  • the declare keyword should be lower case
  • no space between the keyword and opening parenthesis
  • one space after the opening parenthesis
  • one space before the equals sign
  • one space after the equals sign
  • one space before the closing parenthesis
  • no space between the closing parenthesis and terminating semi-colon
  • one space between the closing parenthesis and opening curly brace in a block declaration
  • the opening curly brace should be the last content on the line
  • the closing curly brace in a block declaration should be on a new line
  • the closing curly brace should be column-aligned with the declare keyword
  • the only supported directives are ticks, strict_types, or encoding
• The BigBite.Files.FileName sniff has been updated to include enums.
  Enums should follow the same convention as classes, interfaces, and traits (enum-my-enum.php).

In addition to custom rules, we now also include rules from other standards:

• both pre-increment/decrement (++$i/--$i) and post-increment/decrement ($i++/$i--) are disallowed
  Sniff: SlevomatCodingStandard.Operators.DisallowIncrementAndDecrementOperators
  This has always been our standard, but now it is correctly enforced.

• modern usage of dirname is enforced

  • __DIR__ should be used instead of dirname( __FILE__ )
  • a count should be passed as the second argument of dirname, rather than nested calls

  Sniff: Modernize.FunctionCalls.Dirname

• mixing unkeyed and keyed array items is disallowed
  Sniff: Universal.Arrays.MixedKeyedUnkeyedArray
  Note: this rule will sometimes need to be ignored for taxonomy queries in WP

• interface implementation and class extension lists should be alphabetically sorted
  Sniff: Universal.OOStructures.AlphabeticExtendsImplements

• use statements should be alphabetised
  Sniff: SlevomatCodingStandard.Namespaces.AlphabeticallySortedUses

• usage of grouping in use statements (via {}) is disallowed
  Sniff: SlevomatCodingStandard.Namespaces.DisallowGroupUse

• unused use statements will throw an error
  Sniff: SlevomatCodingStandard.Namespaces.UnusedUses

• loose equality is disallowed
  Sniff: SlevomatCodingStandard.Operators.DisallowEqualOperators

• variable variables are disallowed ($$var)
  Sniff: SlevomatCodingStandard.Variables.DisallowVariableVariable

• unused variables will throw an error
  Sniff: SlevomatCodingStandard.Variables.UnusedVariable

• useless variables will throw an error
  Sniff: SlevomatCodingStandard.Variables.UselessVariable

Documentation

We now no longer include the WordPress-Docs standard from WPCS.
The BigBite ruleset no longer contains any documentation-specific sniffs.
Instead, a new ruleset has been created to encompass these sniffs (BigBiteDocs).
The BigBite ruleset imports BigBiteDocs, so no user action is required to maintain documentation sniffing.

The documentation ruleset itself is now much more comprehensive, and it is here where you are most likely to encounter the most error codes when upgrading.
It is primarily for this reason that we're releasing this as a breaking change, and it's recommended to only think about backporting it to existing projects when one has plenty of time to address the issues it will report.

The most major change is the removal of Squiz.Commenting.FunctionComment in favour of our own custom version (BigBite.Commenting.FunctionComment).
The reason for this is that, although Squiz's version covers most of our function comment standards, there are some areas in which we differ.
Additionally, the Squiz sniff is missing fixers, so all non-conforming comments would need manual effort to resolve.
When upgrading existing projects, this is prohibitively time consuming.
So, we extended the Squiz sniff, modified some of its standards, and added fixers for as many violations as possible.

We've also introduced a sniff to limit the line length of doc comments (BigBite.Commenting.DocCommentLineLength).
This sniff is configurable but, by default:

• lines longer than 80 characters, but shorter than 100, will trigger a warning
• lines longer than 100 characters will trigger an error
• leading indentation does not contribute to the line length
• parameter type hints do not contribute to the line length
• lines starting with Description: will be ignored (to allow plugin/theme comments)
• lines that contain no whitespace (to allow things like URLs)

To configure this sniff:

<rule ref="BigBite.Commenting.DocCommentLineLength">
  <property name="lineLimit" value="100" />
  <property name="absoluteLineLimit" value="150" />
  <property name="includeIndentation" value="true" />
  <property name="descriptorsToIgnore" type="array">
    <element value="Description:" />
    <element value="MyCommentPrefix:" />
  </property>
</rule>

In addition, several new sniffs have been added. They enforce the following:

• generic style array type hints (array<type> instead of type[])
  Sniff: SlevomatCodingStandard.TypeHints.DisallowArrayTypeHintSyntax
• shorthand scalar type hints (int|bool instead of integer|boolean)
  Sniff: SlevomatCodingStandard.TypeHints.LongTypeHints
• type hints to be marked as nullable when the argument's default is null
  Sniff: SlevomatCodingStandard.TypeHints.NullableTypeForNullDefaultValue

Suggestions for upgrading

To upgrade an existing project, first require the new version:

composer require --dev bigbite/phpcs-config:^3.0.0 -W

If this upgrade fails due to the currently-linked PHP version on your system (see screenshot), you can forcibly install it by ignoring the PHP platform requirement (though, really, you should be running at least PHP 8.0):

composer require --dev bigbite/phpcs-config:^3.0.0 -W --ignore-platform-req=php

Once installed, you are likely to see a lot of errors. This can be reduced by running PHP CodeSniffer's fixer:

./vendor/bin/phpcbf .

This may take a few seconds on large projects, but should drastically cut down on the quantity of errors that you'll have to manually fix.

Once that process has finished, you can then run PHPCS to review the errors.
The most likely errors you'll see will be documentation-related.
Our standard for function comments can be found here.
This version of the ruleset introduces sniffs to ensure that code documentation adheres to this standard.

After testing on a few different codebases, the most common violations are as follows:

• "Parameter comment must start with a capital letter" (BigBiteDocs.Commenting.FunctionComment.ParamCommentNotCapital)
  There is a fixer for this, but it will sometimes fail to fix instances of this when there are other violations nearby.
• "Missing @return tag in function comment" (BigBiteDocs.Commenting.FunctionComment.MissingReturn)
  This primarily seems to occur on void-return function/method signatures, when the user's editor is not configured to include the @return tag for void-return function signatures
• "Type hint '[type]' missing for [$param_name]" (BigBiteDocs.Commenting.FunctionComment.[Scalar]TypeHintMissing)
  These violations will have to be manually inspected; for first-party code that doesn't extend WP code, the missing type hints can be added.
  However, for classes that extend WP core classes, the violation(s) will likely have to be ignored, as WP doesn't type hint very thorougly.
  Since method argument type hints are contravariant (they can not narrow a type, only broaden), adding type hints to methods that don't have them in the parent class will cause a fatal error.
  Be careful when fixing these violations.
• "Line exceeds 80 characters; contains n characters" (BigBite.Commenting.DocCommentLineLength.TooLong)
  There is no fixer for this, as it would be challenging to determine at what point it would be sensible to break a long comment onto multiple lines.
  If using PHPStan types, it is likely preferable to ignore the violation, rather than attempt to fix it.
  An attempt has been made to avoid flagging on PHPStan types, but it is unavoidable in some cases.

As you can see, the primary cause of violations during upgrade are documentation blocks not adhering to Big Bite's standard.
So, to ease upgrading, it may be worth considering whether to ignore the rule completely whilst the rest of the violations are being rectified.
This can be done via the project's PHPCS config file, though please consult with the project lead prior to taking this approach.

<rule ref="./vendor/bigbite/phpcs-config/BigBite">
  <exclude name="BigBiteDocs.Commenting.FunctionComment"/>
</rule>