5.0 | Proposal: add return types to select methods #391
Comments
|
This sounds great! You mentioned |
@greg0ire 3.x has a PHP 5.4 minimum, so that's a no-go. As for 4.x, I'd have to see, though there's enough to do for 4.0 already, so I think it might be better to leave it till 5.0. |
|
I think the more types the better, so I'd vote yes for this. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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 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 checkRequirements(): voidpublic 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 getFixedCount(): 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(): \RecursiveIteratorprotected 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\Generators\*:All methods will get the
voidreturn type.In
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:final public function process(...): voidprotected function processPattern(...): array|false(* PHP 8.0+)protected function prepareError(...): stringabstract protected function getPatterns(): arrayprotected function registerSupplementary(): arrayprotected function processSupplementary(...): voidIn
PHP_CodeSniffer\Sniffs\AbstractScopeSniff:abstract protected function processTokenWithinScope(...): ?intabstract protected function processTokenOutsideScope(...): ?intIn
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 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 printInstalledStandards(): voidIn
PHP_CodeSniffer\Util\Timing:public static function startTiming(): voidpublic static function getDuration(): 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
The text was updated successfully, but these errors were encountered: