YoastCS 3.0.0 roadmap

[jrfnl]

This is an issue with a high-level write-up and proposal for YoastCS 3.0.0, so the intentions for YoastCS 3.0.0 are documented and can be discussed.

TL;DR

New minimum requirements:

• PHP 7.2 🆕
• PHP_CodeSniffer 3.5.4 3.8.0
• WordPressCS 3.0.0
• PHPCompatibility 10.0.0

Add new dependencies and implement use of/selectively add rules from:

• PHPCSUtils
• PHPCSExtra
• VariableAnalysis
• SlevomatCodingStandard

This includes removing some YoastCS native sniffs in favour of sniffs from the above mentioned standards, including WPCS.

Note: New rule additions will be pulled in separate PRs so these proposals can be reviewed and evaluated individually.

The planning is for YoastCS 3.0.0 to be released soon after WPCS 3.0.0 and PHPCompatibility 10.0.0 have been released.

Developments in the wider PHP_CodeSniffer sphere

PHPCSUtils

The new PHPCSUtils library offers a number of sniff helper utilities and PHPCS cross-version compatibility utilities which can be useful for some of the sniffs in YoastCS.

PHPCSUtils has been set up to support and recognize all PHP syntaxes, including modern PHP, from namespaced code to arrow functions and is fully unit tested.

PHPCSUtils does not contain any sniffs (other than abstract base sniffs to use as building blocks).

Originally the intention was that this library would be added to PHPCS itself (without the cross-version helpers), but that bounced off.

PHPCSUtils supports PHPCS 2.6.0 3.7.1 - current, including the upcoming PHPCS 4.x and has a minimum PHP requirement of PHP 5.4.

Also see: https://phpcsutils.com/

PHPCSExtra

The new PHPCSExtra standard is developed on top of PHPCSUtils and offers some new sniffs which we may want to add to YoastCS.

A few sniffs from that standard can also be used to replace custom sniffs in the YoastCS standard.

PHPCSExtra has a minimum PHPCS requirement of PHPCS 3.3.1 3.7.1 and has a minimum PHP requirement of PHP 5.4.

WordPressCS 3.0.0

WordPressCS 3.0.0 will add dependencies to both PHPCSUtils as well as PHPCSExtra.

A number of the more generically useful sniffs which are also useful outside of a WP context will be moved from WPCS to PHPCSExtra to make them more easily discoverable by the wider PHP community.

PHPCSUtils will be used to help make the WPCS sniffs better able to handle modern PHP.

WPCS 3.0.0 is expected to include quite some new sniffs, either WPCS native or from PHPCSExtra, to implement the proposals outlined in the recent Make post.

WordPressCS 3.0.0 will have a minimum PHPCS requirement of PHPCS 3.5.0 3.7.1 and has a minimum PHP requirement of PHP 5.4.

WordPressCS 3.0.0 is expected to be released some time over the next three months.

Also see: WordPressCS 3.0.0 planning and roadmap

PHPCompatibility 10.0.0

PHPCompatibility 10.0.0 will add a dependency to and implement PHPCSUtils, both for improved handling of modern PHP as well as for improved PHPCS cross-version compatibility.

PHPCompatibility 10.0.0 will have a minimum PHPCS requirement of PHPCS 2.6.0 3.7.1 and will have a minimum PHP requirement of PHP 5.4. (was 5.3).

PHPCompatibility 10.0.0 is expected to be released some time over the next three months.

Also see: https://github.com/PHPCompatibility/PHPCompatibility/milestone/26

Other interesting standards

There are a number of other interesting external standards for PHP_CodeSniffer which I have been auditing over the past few months as candidates for inclusion in YoastCS.

VariableAnalysis

The VariableAnalysis standard is an old standard abandoned by the original author and currently maintained by Payton Swick (Automattic).

This standard reports on uses of undefined variables as well as unused variables.

The standard has started implementing PHPCSUtils as well and I've been working on fixing a number of bugs and, together with the maintainer, making the historically grown code better maintainable.

VariableAnalysis has a minimum PHPCS requirement of PHPCS 3.1 3.5.4 and has a minimum PHP requirement of PHP 5.6.

ImportDetection

The ImportDetection standard - also maintained by Payton Swick - shows warnings if a symbol (function, constant, class) is used and is not defined directly, imported explicitly, nor has its namespace imported.

This library is useful, but not very configurable which makes it - at this time - not the preferred choice for inclusion in YoastCS.

Security

The Security standard is aimed at finding vulnerabilities and weaknesses related to security in PHP code.

The standard is problematic to use as it doesn't comply with some PHPCS basics (expected to be fixed in the next release).

The standard is also currently too prone to false positives to be considered for inclusion in YoastCS.

CognitiveComplexity

The CognitiveComplexity standard is a one-sniff fork of a sniff originally in the Simplify standard and improved and maintained by Rarst.

It analyses code for Cognitive Complexity metric by SonarSource and alerts if the cognitive complexity is too high.

This standard would be a useful inclusion for YoastCS, but would require code refactoring in a number of plugins to allow the code to pass the checks.

I propose to keep this standard in mind for future addition.

CognitiveComplexity has a minimum PHPCS requirement of PHPCS 3.5 and has a minimum PHP requirement of PHP 7.2.

Object Calisthenics

The Object Calisthenics standard set of rules in object-oriented code, that focuses on maintainability, readability, testability and comprehensibility.

The standard is problematic to use as it doesn't comply with some PHPCS basics.

The rules in the standard are also too fiddly for the Yoast codebases, so for that reason, this standard has been rejected.

Slevomat Coding Standard

The Slevomat Coding Standard was originally developed for the Slevomat company, but has gained a large following and is actively maintained.

The standard has (had) some issues with it not complying with some PHPCS basics making it problematic to use, but I've been fixing these and all such known issues should be fixed by the next release.

The Slevomat standard can never be used as a standard as it contains conflicting rules. Individual sniffs from the standard should be included instead.

The standard contains a lot of sniffs for modern PHP formatting and best practices and most of these sniffs are highly configurable.
The majority of sniffs from the Slevomat standard include fixers to auto-fix code which doesn't comply.

While some sniffs are buggy at times, the team behind it is very responsive and bugs are fixed promptly.

As the minimum PHP requirement for this standard is PHP 7.1 7.2, it couldn't previously be used as it would cause a conflict with the minimum requirements on Composer install, however, as some of the other dev requirements for the plugins now have higher PHP requirements too and --ignore-platform-reqs is now used by default, this standard is now a viable candidate for inclusion in YoastCS and has my recommendation.

Slevomat Coding Standard has a minimum PHPCS requirement of PHPCS 3.5.4 and has a minimum PHP requirement of PHP 7.1.

Beyond YoastCS 3.0.0

I'm working on creating a number of additional external PHPCS standards which will be candidates for inclusion in YoastCS once released.

Think along the lines of:

• PHPUnitCompatibility (helpers to upgrade PHPUnit code for higher PHPUnit versions)
• PHPUnit Best Practices (using the right assertions, using annotations correctly etc)
• PSR5 (documentation analysis based on PSR5)
• PSR19 (documentation analysis based on PSR19)
• PHPModernizer (finding opportunities to modernize code)

[jrfnl]

Closing as fixed with the addition of PHPCSExtra, Slevomat, VariableAnalysis and WordPress VIP to YoastCS 3.0.