You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
At this time, it has not yet been decided what the minimum supported PHP version will be for PHPCS 5.0, though it will be PHP 7.2 or higher (as PHP 7.2 is the new minimum supported PHP version for PHCPS 4.0).
PHP 7.2 allows for:
Adding parameter type declarations, with the exception of union/intersection/DNF/mixed types.
Adding return type declarations, with the exception of union/intersection/DNF/mixed types.
Null/true/false as in union types or as stand-alone types (PHP 8.0/8/2)
Parameter type declarations in PHP are contravariant, which means that overloaded methods in child classes can widen the type.
Return type declarations in PHP are covariant, which means that overloaded methods in child classes can make the type more narrow.
Full support for contravariance and covariance was only added in PHP 7.4.
Proposal
I propose to add return type declarations to the public/protected methods in PHPCS 5.0 as per the list below - providing the minimum PHP version will allow for it (to be decided and discussed in a separate issue).
If any of the signature changes can not be made yet due to the minimum PHP version not allowing for it (yet), those changes (and only those) will move to the first major release which has the required minimum PHP version.
Detailed proposal
Notes about the detailed proposal:
Signatures of private methods methods are excluded from the below list as they don't affect the public API, but these will be updated too.
Methods for which no legal return type can be added, have been left out of the list.
Methods which will need to be updated by extension and do not deviate from the change to the "parent" method, are not listed repetitively.
The return types have largely been based on the currently documented types, which may not be correct (in which case the type will be changed to the real type).
The list is based on the current state of the codebase and is subject to change.
In PHP_CodeSniffer\Config:
public function __get(...): mixed (* PHP 8.0+)
public function __set(...): void
public function __isset(...): bool
public function __unset(...): void
public function getSettings(): array
public function setSettings(...): void
public function setCommandLineValues(...): void
public function restoreDefaults(): void
public function processShortArgument(...): void
public function processLongArgument(...): void
public function processUnknownArgument(...): void
public function processFilePath(...): void
public function printUsage(): void
public function printPHPCSUsage(): void
public function printPHPCBFUsage(): void
public static function getConfigData(...): ?string
public static function getExecutablePath(...): ?string
public function setConfigData(...): bool
public static function getAllConfigData(): array
public function prepareConfigDataForDisplay(...): string
public function findPrevious(...): int|false (* PHP 8.0+)
public function findNext(...): int|false (* PHP 8.0+)
public function findStartOfStatement(...): int
public function findEndOfStatement(...): int
public function findFirstOnLine(...): int|false (* PHP 8.0+)
public function hasCondition(...): bool
public function getCondition(...): int|false (* PHP 8.0+)
public function findExtendedClassName(...): string|false (* PHP 8.0+)
public function findImplementedInterfaceNames(...): array|false (* PHP 8.0+)
In PHP_CodeSniffer\Files\DummyFile:
public function setErrorCounts(...): void
In PHP_CodeSniffer\Files\FileList:
public function addFile(...): void
public function rewind(): void
public function current(): \PHP_CodeSniffer\Files\File
public function key(): ?string
public function next(): void
public function valid(): bool
public function count(): int
In PHP_CodeSniffer\Filters\Filter:
public function accept(): bool
public function getChildren(): \RecursiveFilterIterator
protected function shouldProcessFile(...): bool
protected function shouldIgnorePath(...): bool
In PHP_CodeSniffer\Filters\ExactMatch:
abstract protected function getDisallowedFiles(): array
abstract protected function getAllowedFiles(): array
In PHP_CodeSniffer\Filters\Git*:
protected function exec(...): array
In PHP_CodeSniffer\Generators\Generator:
protected function getTitle(...): string
public function generate(): void
abstract protected function processSniff(...): void
In PHP_CodeSniffer\Reports\Report:
public function generateFileReport(...): bool
public function generate(...): void
In PHP_CodeSniffer\Sniffs\Sniff:
public function register(): array
Note: the public function process(...) method will not get a return type as int|void is an illegal type, even in PHP 8.0+ and ?int is incompatible with a child class having a void return type. Classes implementing the interface can still add a return type if the type returned from their implementation is consistently void or int.
In PHP_CodeSniffer\Sniffs\AbstractArraySniff:
public function process(...): void
abstract protected function processSingleLineArray(...): void
abstract protected function processMultiLineArray(...): void
In PHP_CodeSniffer\Sniffs\AbstractPatternSniff:
protected function processPattern(...): array|false (* PHP 8.0+)
protected function prepareError(...): string
abstract protected function getPatterns(): array
protected function registerSupplementary(): array
protected function processSupplementary(...): void
In PHP_CodeSniffer\Sniffs\DeprecatedSniff:
public function getDeprecationVersion(): string
public function getRemovalVersion(): string
public function getDeprecationMessage(): string
In PHP_CodeSniffer\Tokenizers\Tokenizer:
protected function isMinifiedContent(...): bool
public function getTokens(): array
abstract protected function tokenize(...): array
abstract protected function processAdditional(): void
public function replaceTabsInToken(...): void
In PHP_CodeSniffer\Tokenizers\Comment:
public function tokenizeString(...): array
In PHP_CodeSniffer\Tokenizers\PHP:
public static function standardiseToken(...): array
public static function resolveSimpleToken(...): array
In PHP_CodeSniffer\Util\Cache:
public static function load(...): void
public static function save(): void
public static function get(...): mixed (* PHP 8.0+)
public static function set(...): void
public static function getSize(): int
In PHP_CodeSniffer\Util\Common:
public static function isPharFile(...): bool
public static function isReadable(...): bool
public static function realpath(...): string|false (* PHP 8.0+)
public static function stripBasepath(...): string
public static function detectLineEndings(...): string
public static function isStdinATTY(): bool
public static function escapeshellcmd(...): string
public static function prepareForOutput(...): string
public static function stripColors(...): string
public static function isCamelCaps(...): bool
public static function isUnderscoreName(...): bool
public static function suggestType(...): string
public static function getSniffCode(...): string
public static function cleanSniffClass(...): string
In PHP_CodeSniffer\Util\Standards:
public static function getInstalledStandardPaths(): array
public static function getInstalledStandardDetails(...): array
public static function getInstalledStandards(...): array
public static function isInstalledStandard(...): bool
public static function getInstalledStandardPath(...): ?string
public static function prepareInstalledStandardsForDisplay(): string
public static function printInstalledStandards(): void
In PHP_CodeSniffer\Util\Timing:
public static function startTiming(): void
public static function getDuration(): float
public static function getDurationSince(): float
public static function getHumanReadableDuration(...): string
public static function printRunTime(...): void
In PHP_CodeSniffer\Util\Tokens:
public static function tokenName(...): string
public static function getHighestWeightedToken(...): int|false (* PHP 8.0+)
In PHP_CodeSniffer\Tests\Standards\AbstractSniffUnitTest:
protected function getTestFiles(...): array
protected function shouldSkipTest(): bool
public function setCliValues(...): void
protected function getErrorList(): array
protected function getWarningList(): array
[*] The above list may still receive some updates over time. If/when updates are made, a comment will be left in the thread detailing the updates which were made.
New methods
Any new methods being introduced to PHPCS during the lifetime of the 4.x major should be considered outside the scope of this issue and can get a return type declaration at their introduction, providing the minimum PHP version allows for it.
New methods which need a type not yet supported via the current minimum PHP version should be added to the list above.
BC considerations
As return types are covariant, adding these type declarations in PHPCS 5.0 constitutes a backward compatibility break as the method signature of overloaded/implemented methods MUST be updated to include a compatible return type declaration.
Suggested Migration Path for External Standards
During the lifetime of PHPCS 4.x, external standards are encouraged to:
Add return type declarations to their code, in line with the above proposal
Add strict_types=1 declarations to their files.
Use tooling like PHPStan and/or Psalm to find further type juggling issues.
None of this can/will be enforced, but external standards using the lifetime of PHPCS 4.x to action the above will be better prepared for supporting PHPCS 5.x when the time comes.
Setting the scene
At this time, it has not yet been decided what the minimum supported PHP version will be for PHPCS 5.0, though it will be PHP 7.2 or higher (as PHP 7.2 is the new minimum supported PHP version for PHCPS 4.0).
PHP 7.2 allows for:
PHP 7.2 does not support:
Parameter type declarations in PHP are contravariant, which means that overloaded methods in child classes can widen the type.
Return type declarations in PHP are covariant, which means that overloaded methods in child classes can make the type more narrow.
Full support for contravariance and covariance was only added in PHP 7.4.
Proposal
I propose to add return type declarations to the public/protected methods in PHPCS 5.0 as per the list below - providing the minimum PHP version will allow for it (to be decided and discussed in a separate issue).
If any of the signature changes can not be made yet due to the minimum PHP version not allowing for it (yet), those changes (and only those) will move to the first major release which has the required minimum PHP version.
Detailed proposal
Notes about the detailed proposal:
privatemethods methods are excluded from the below list as they don't affect the public API, but these will be updated too.In
PHP_CodeSniffer\Config:public function __get(...): mixed(* PHP 8.0+)public function __set(...): voidpublic function __isset(...): boolpublic function __unset(...): voidpublic function getSettings(): arraypublic function setSettings(...): voidpublic function setCommandLineValues(...): voidpublic function restoreDefaults(): voidpublic function processShortArgument(...): voidpublic function processLongArgument(...): voidpublic function processUnknownArgument(...): voidpublic function processFilePath(...): voidpublic function printUsage(): voidpublic function printPHPCSUsage(): voidpublic function printPHPCBFUsage(): voidpublic static function getConfigData(...): ?stringpublic static function getExecutablePath(...): ?stringpublic function setConfigData(...): boolpublic static function getAllConfigData(): arraypublic function prepareConfigDataForDisplay(...): stringpublic function printConfigData(...): voidIn
PHP_CodeSniffer\Fixer:public function startFile(...): voidpublic function fixFile(): boolpublic function generateDiff(...): stringpublic function getFixCount(): intpublic function getContents(): stringpublic function getTokenContent(...): stringpublic function endChangeset(): ?(under discussion, see Ensure that Fixer::endChangeset() returns the real outcome #375)public function rollbackChangeset(): voidpublic function replaceToken(...): boolpublic function revertToken(...): boolpublic function substrToken(...): boolpublic function addNewline(...): boolpublic function addNewlineBefore(...): boolpublic function addContent(...): boolpublic function addContentBefore(...): boolpublic function changeCodeBlockIndent(...): voidIn
PHP_CodeSniffer\Reporter:public function printReports(): boolpublic function printReport(...): voidpublic function cacheFileReport(...): voidpublic function prepareFileReport(...): arrayIn
PHP_CodeSniffer\Ruleset:public function explain(): voidpublic function hasSniffDeprecations(): boolpublic function showSniffDeprecations(): voidpublic function processRuleset(...): arraypublic function registerSniffs(...): voidpublic function populateTokenListeners(): voidpublic function setSniffProperty(...): voidpublic function getIgnorePatterns(...): arraypublic function getIncludePatterns(...): arrayIn
PHP_CodeSniffer\Runner:public function runPHPCS(): intpublic function runPHPCBF(): intpublic function init(): voidpublic function handleErrors(...): boolpublic function processFile(...): voidpublic function printProgress(...): voidIn
PHP_CodeSniffer\Files\File:public function setContent(): voidpublic function reloadContent(): voidpublic function disableCaching(): voidpublic function process(): voidpublic function parse(): voidpublic function getTokens(): arraypublic function cleanUp(): voidpublic function addError(...): boolpublic function addWarning(...): boolpublic function addErrorOnLine(...): boolpublic function addWarningOnLine(...): boolpublic function addFixableError(...): boolpublic function addFixableWarning(...): boolprotected function addMessage(...): boolpublic function recordMetric(...): boolpublic function getErrorCount(): intpublic function getWarningCount(): intpublic function getFixableCount(): intpublic function getFixableErrorCount(): intpublic function getFixableWarningCount(): intpublic function getFixedCount(): intpublic function getFixedErrorCount(): intpublic function getFixedWarningCount(): intpublic function getFirstRunCount(): intpublic function getIgnoredLines(): arraypublic function getErrors(): arraypublic function getWarnings(): arraypublic function getMetrics(): arraypublic function getListenerTimes(): arraypublic function getFilename(): stringpublic function getDeclarationName(...): stringpublic function getMethodParameters(...): arraypublic function getMethodProperties(...): arraypublic function getMemberProperties(...): arraypublic function getClassProperties(...): arraypublic function isReference(...): boolpublic function getTokensAsString(...): stringpublic function findPrevious(...): int|false(* PHP 8.0+)public function findNext(...): int|false(* PHP 8.0+)public function findStartOfStatement(...): intpublic function findEndOfStatement(...): intpublic function findFirstOnLine(...): int|false(* PHP 8.0+)public function hasCondition(...): boolpublic function getCondition(...): int|false(* PHP 8.0+)public function findExtendedClassName(...): string|false(* PHP 8.0+)public function findImplementedInterfaceNames(...): array|false(* PHP 8.0+)In
PHP_CodeSniffer\Files\DummyFile:public function setErrorCounts(...): voidIn
PHP_CodeSniffer\Files\FileList:public function addFile(...): voidpublic function rewind(): voidpublic function current(): \PHP_CodeSniffer\Files\Filepublic function key(): ?stringpublic function next(): voidpublic function valid(): boolpublic function count(): intIn
PHP_CodeSniffer\Filters\Filter:public function accept(): boolpublic function getChildren(): \RecursiveFilterIteratorprotected function shouldProcessFile(...): boolprotected function shouldIgnorePath(...): boolIn
PHP_CodeSniffer\Filters\ExactMatch:abstract protected function getDisallowedFiles(): arrayabstract protected function getAllowedFiles(): arrayIn
PHP_CodeSniffer\Filters\Git*:protected function exec(...): arrayIn
PHP_CodeSniffer\Generators\Generator:protected function getTitle(...): stringpublic function generate(): voidabstract protected function processSniff(...): voidIn
PHP_CodeSniffer\Reports\Report:public function generateFileReport(...): boolpublic function generate(...): voidIn
PHP_CodeSniffer\Sniffs\Sniff:public function register(): arrayNote: the
public function process(...)method will not get a return type asint|voidis an illegal type, even in PHP 8.0+ and?intis incompatible with a child class having avoidreturn type.Classes implementing the interface can still add a return type if the type returned from their implementation is consistently
voidorint.In
PHP_CodeSniffer\Sniffs\AbstractArraySniff:public function process(...): voidabstract protected function processSingleLineArray(...): voidabstract protected function processMultiLineArray(...): voidIn
PHP_CodeSniffer\Sniffs\AbstractPatternSniff:protected function processPattern(...): array|false(* PHP 8.0+)protected function prepareError(...): stringabstract protected function getPatterns(): arrayprotected function registerSupplementary(): arrayprotected function processSupplementary(...): voidIn
PHP_CodeSniffer\Sniffs\DeprecatedSniff:public function getDeprecationVersion(): stringpublic function getRemovalVersion(): stringpublic function getDeprecationMessage(): stringIn
PHP_CodeSniffer\Tokenizers\Tokenizer:protected function isMinifiedContent(...): boolpublic function getTokens(): arrayabstract protected function tokenize(...): arrayabstract protected function processAdditional(): voidpublic function replaceTabsInToken(...): voidIn
PHP_CodeSniffer\Tokenizers\Comment:public function tokenizeString(...): arrayIn
PHP_CodeSniffer\Tokenizers\PHP:public static function standardiseToken(...): arraypublic static function resolveSimpleToken(...): arrayIn
PHP_CodeSniffer\Util\Cache:public static function load(...): voidpublic static function save(): voidpublic static function get(...): mixed(* PHP 8.0+)public static function set(...): voidpublic static function getSize(): intIn
PHP_CodeSniffer\Util\Common:public static function isPharFile(...): boolpublic static function isReadable(...): boolpublic static function realpath(...): string|false(* PHP 8.0+)public static function stripBasepath(...): stringpublic static function detectLineEndings(...): stringpublic static function isStdinATTY(): boolpublic static function escapeshellcmd(...): stringpublic static function prepareForOutput(...): stringpublic static function stripColors(...): stringpublic static function isCamelCaps(...): boolpublic static function isUnderscoreName(...): boolpublic static function suggestType(...): stringpublic static function getSniffCode(...): stringpublic static function cleanSniffClass(...): stringIn
PHP_CodeSniffer\Util\Standards:public static function getInstalledStandardPaths(): arraypublic static function getInstalledStandardDetails(...): arraypublic static function getInstalledStandards(...): arraypublic static function isInstalledStandard(...): boolpublic static function getInstalledStandardPath(...): ?stringpublic static function prepareInstalledStandardsForDisplay(): stringpublic static function printInstalledStandards(): voidIn
PHP_CodeSniffer\Util\Timing:public static function startTiming(): voidpublic static function getDuration(): floatpublic static function getDurationSince(): floatpublic static function getHumanReadableDuration(...): stringpublic static function printRunTime(...): voidIn
PHP_CodeSniffer\Util\Tokens:public static function tokenName(...): stringpublic static function getHighestWeightedToken(...): int|false(* PHP 8.0+)In
PHP_CodeSniffer\Tests\Standards\AbstractSniffUnitTest:protected function getTestFiles(...): arrayprotected function shouldSkipTest(): boolpublic function setCliValues(...): voidprotected function getErrorList(): arrayprotected function getWarningList(): array[*] The above list may still receive some updates over time. If/when updates are made, a comment will be left in the thread detailing the updates which were made.
New methods
Any new methods being introduced to PHPCS during the lifetime of the 4.x major should be considered outside the scope of this issue and can get a return type declaration at their introduction, providing the minimum PHP version allows for it.
New methods which need a type not yet supported via the current minimum PHP version should be added to the list above.
BC considerations
As return types are covariant, adding these type declarations in PHPCS 5.0 constitutes a backward compatibility break as the method signature of overloaded/implemented methods MUST be updated to include a compatible return type declaration.
Suggested Migration Path for External Standards
During the lifetime of PHPCS 4.x, external standards are encouraged to:
strict_types=1declarations to their files.None of this can/will be enforced, but external standards using the lifetime of PHPCS 4.x to action the above will be better prepared for supporting PHPCS 5.x when the time comes.
Opinions ?
/cc @asispts @dingo-d @fredden @GaryJones @greg0ire @kukulich @michalbundyra @Ocramius @sirbrillig @stronk7 @weierophinney @wimg