This ticket should be seen as an advance notice and is intended to inform users of PHPCSUtils of what the future will hold regarding PHPCS and PHP version support.
Current situation
PHPCS 3.x has a minimum supported PHP version of 5.4.
PHPCS 4.x will have a minimum of PHP 7.2.
PHPCSUtils has a minimum PHP version of 5.4 and all code in PHPCSUtils is compatible with PHPCS 3.x as well as PHPCS 4.0 (in its current state).
This means that using PHPCSUtils can help external standards to be better prepared for PHPCS 4.x.
It also means that, for the time being, it will allow external standards to support both PHPCS 3.x as well as 4.x (once released). At least for a while.
Version support strategies and planning
Once PHPCS 4.0 has been released, the PHPCS 3.x branch becomes unsupported, aside from essential security fixes and fixes for runtime support for a new PHP version (for about a year). Bug fixes and support for new PHP syntaxes will only be added to PHPCS 4.x.
While PHPCSUtils does not want to be overly aggressive with dropping support for older PHPCS versions, it was decided a while ago that PHPCSUtils will not backfill syntax support for new PHP syntaxes (anymore) and will up the minimum PHPCS version whenever needed to gain support for new PHP syntaxes.
PHP has been adding new syntaxes with increasing frequency over the past few years. PHPCS was a little behind with supporting those new syntaxes, but once PHPCS 3.10.0 is released (expected later this week), that backlog is gone and PHPCS will (finally) have caught up.
So far, so good and until PHPCS adds support for new PHP 8.4 syntaxes, I expect the minimum supported PHPCS version for PHPCSUtils can stay at 3.10.0 for a while.
It remains to be seen which will land first, PHPCS 4.0 or syntax support for PHP 8.4 syntaxes (in PHPCS 3.x), but the expectation (hope), at this time, is that PHPCS 4.0 will be released sooner rather than later, though that in part depends on when I can finish some additional utilities I've been building for PHPCSUtils to make the switch to PHPCS 4.0/cross-version PHPCS 3.x-4.x support easier for external standards (I'd like to get those features ready and released before releasing PHPCS 4.0).
However, once PHPCS 4.0 is released and the first new PHP syntax support PR has been merged into PHPCS 4.x, PHPCSUtils will drop support for PHPCS 3.x.
This also means that, by that time, PHP < 7.2 will no longer need to be supported.
Once PHPCSUtils drops support for PHPCS 3.x, PHPCS 4.x will be the only supported version.
There is no intention to maintain multiple branches, one with PHPCS 3,x support, one for PHPCS 4.x support.
Tasks
When support for PHPCS 3.x / PHP < 7.2 is being dropped, the following code modernizations should be made:
[ ] Remove work-arounds which are in place for cross-version PHPCS 3.x/4.x support.
[ ] Remove any incidental support for CSS/JS.
[ ] Deprecate specific features which are in place for cross-version PHPCS 3.x/4.x support. (in particular in the TestUtils)
[ ] Simplify the test code (remove all token calculation ternaries related to cross-version PHPCS 3.x/4.x support)
[ ] Drop support for PHPUnit < 8.x, including for the TestUtils.
[ ] Use ::class whenever possible (especially in the tests).
[ ] Declare constant arrays as class constants instead of as class properties
Note: this change can only be made for private properties (and protected properties in final classes) as for public properties this would be a breaking change.
[ ] In the tests, remove overloaded setUpTestFile() methods which are only in place to set the static $caseFile property. Set the property using a constant scalar expression in the property declaration instead.
In the next major release (yet to be decided if this will coincide with the version drop or not):
[ ] Deprecate/remove specific features which are in place for cross-version PHPCS 3.x/4.x support. (in particular in the TestUtils)
[ ] Add (scalar) type declarations whenever possible.
[ ] Declare constant arrays as class constants instead of as class properties for public properties.
Note: this list is by no means complete, but is intended as a starting point.
This ticket should be seen as an advance notice and is intended to inform users of PHPCSUtils of what the future will hold regarding PHPCS and PHP version support.
Current situation
PHPCS 3.x has a minimum supported PHP version of 5.4. PHPCS 4.x will have a minimum of PHP 7.2.
PHPCSUtils has a minimum PHP version of 5.4 and all code in PHPCSUtils is compatible with PHPCS 3.x as well as PHPCS 4.0 (in its current state).
This means that using PHPCSUtils can help external standards to be better prepared for PHPCS 4.x. It also means that, for the time being, it will allow external standards to support both PHPCS 3.x as well as 4.x (once released). At least for a while.
Version support strategies and planning
Once PHPCS 4.0 has been released, the PHPCS 3.x branch becomes unsupported, aside from essential security fixes and fixes for runtime support for a new PHP version (for about a year). Bug fixes and support for new PHP syntaxes will only be added to PHPCS 4.x.
While PHPCSUtils does not want to be overly aggressive with dropping support for older PHPCS versions, it was decided a while ago that PHPCSUtils will not backfill syntax support for new PHP syntaxes (anymore) and will up the minimum PHPCS version whenever needed to gain support for new PHP syntaxes.
PHP has been adding new syntaxes with increasing frequency over the past few years. PHPCS was a little behind with supporting those new syntaxes, but once PHPCS 3.10.0 is released (expected later this week), that backlog is gone and PHPCS will (finally) have caught up.
So far, so good and until PHPCS adds support for new PHP 8.4 syntaxes, I expect the minimum supported PHPCS version for PHPCSUtils can stay at 3.10.0 for a while.
It remains to be seen which will land first, PHPCS 4.0 or syntax support for PHP 8.4 syntaxes (in PHPCS 3.x), but the expectation (hope), at this time, is that PHPCS 4.0 will be released sooner rather than later, though that in part depends on when I can finish some additional utilities I've been building for PHPCSUtils to make the switch to PHPCS 4.0/cross-version PHPCS 3.x-4.x support easier for external standards (I'd like to get those features ready and released before releasing PHPCS 4.0).
However, once PHPCS 4.0 is released and the first new PHP syntax support PR has been merged into PHPCS 4.x, PHPCSUtils will drop support for PHPCS 3.x.
This also means that, by that time, PHP < 7.2 will no longer need to be supported.
Once PHPCSUtils drops support for PHPCS 3.x, PHPCS 4.x will be the only supported version. There is no intention to maintain multiple branches, one with PHPCS 3,x support, one for PHPCS 4.x support.
Tasks
When support for PHPCS 3.x / PHP < 7.2 is being dropped, the following code modernizations should be made:
::classwhenever possible (especially in the tests).privateproperties (andprotectedproperties infinalclasses) as forpublicproperties this would be a breaking change.setUpTestFile()methods which are only in place to set the static$caseFileproperty. Set the property using a constant scalar expression in the property declaration instead.In the next major release (yet to be decided if this will coincide with the version drop or not):
publicproperties.Note: this list is by no means complete, but is intended as a starting point.