diff --git a/PHPCSUtils/BackCompat/BCFile.php b/PHPCSUtils/BackCompat/BCFile.php index b67f7128..f2dc106d 100644 --- a/PHPCSUtils/BackCompat/BCFile.php +++ b/PHPCSUtils/BackCompat/BCFile.php @@ -573,6 +573,7 @@ public static function getMethodParameters(File $phpcsFile, $stackPtr) * - PHPCS 3.5.0: The Exception thrown changed from a `\PHP_CodeSniffer\Exceptions\TokenizerException` * to `\PHP_CodeSniffer\Exceptions\RuntimeException`. * - PHPCS 3.5.3: Added support for PHP 7.4 `T_FN` arrow functions. + * - PHPCS 3.5.6: Added support for PHP 8.0 `static` return types. * - PHPCS 3.5.7: Added support for namespace operators in type declarations. PHPCS#3066. * - PHPCS 3.6.0: Added support for PHP 8.0 union types. PHPCS#3032. * - PHPCS 3.6.0: Added new `"return_type_end_token"` index. PHPCS#3153. @@ -582,7 +583,7 @@ public static function getMethodParameters(File $phpcsFile, $stackPtr) * * @since 1.0.0 * @since 1.0.0-alpha2 Added BC support for PHP 7.4 arrow functions. - * @since 1.0.0-alpha3 Added support for PHP 8.0 static return type (expected in future PHPCS release). + * @since 1.0.0-alpha3 Added support for PHP 8.0 static return type. * * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned. * @param int $stackPtr The position in the stack of the function token to @@ -1229,6 +1230,7 @@ public static function getTokensAsString(File $phpcsFile, $start, $length, $orig * - Introduced in PHPCS 2.1.0. * - PHPCS 2.6.2: New optional `$ignore` parameter to selectively ignore stop points. * - PHPCS 3.5.5: Added support for PHP 7.4 `T_FN` arrow functions. + * - PHPCS 3.5.7: Bug fix: Heredoc/Nowdoc was not always handled correctly. PHPCS#2883 * * @see \PHP_CodeSniffer\Files\File::findStartOfStatement() Original source. * diff --git a/PHPCSUtils/BackCompat/BCTokens.php b/PHPCSUtils/BackCompat/BCTokens.php index fb20620e..e1b62005 100644 --- a/PHPCSUtils/BackCompat/BCTokens.php +++ b/PHPCSUtils/BackCompat/BCTokens.php @@ -55,7 +55,7 @@ * @method static array methodPrefixes() Tokens that can prefix a method name. * @method static array scopeModifiers() Tokens that represent scope modifiers. * @method static array stringTokens() Tokens that represent strings. - * Note that `T_STRINGS` are NOT represented in this list as this list + * Note that `T_STRING`s are NOT represented in this list as this list * is about _text_ strings. */ class BCTokens diff --git a/PHPCSUtils/Tokens/Collections.php b/PHPCSUtils/Tokens/Collections.php index f80c9ef3..47e60763 100644 --- a/PHPCSUtils/Tokens/Collections.php +++ b/PHPCSUtils/Tokens/Collections.php @@ -78,6 +78,8 @@ class Collections /** * Tokens which are used to create arrays. * + * @see \PHPCSUtils\Tokens\Collections::$arrayTokensBC Related property containing tokens used + * for arrays (PHPCS cross-version). * @see \PHPCSUtils\Tokens\Collections::$shortArrayTokens Related property containing only tokens used * for short arrays. * @@ -98,7 +100,7 @@ class Collections * Should only be used selectively. * * @see \PHPCSUtils\Tokens\Collections::$shortArrayTokensBC Related property containing only tokens used - * for short arrays (cross-version). + * for short arrays (PHPCS cross-version). * * @since 1.0.0 * @@ -180,6 +182,8 @@ class Collections /** * Tokens which are used to create lists. * + * @see \PHPCSUtils\Tokens\Collections::$listTokensBC Related property containing tokens used + * for lists (PHPCS cross-version). * @see \PHPCSUtils\Tokens\Collections::$shortListTokens Related property containing only tokens used * for short lists. * @@ -252,8 +256,7 @@ class Collections * * @since 1.0.0-alpha3 * - * @deprecated 1.0.0-alpha4 Use the {@see \PHPCSUtils\Tokens\Collections::objectOperators()} - * method instead. + * @deprecated 1.0.0-alpha4 Use the {@see Collections::objectOperators()} method instead. * * @var array => */ @@ -322,8 +325,7 @@ class Collections * * @since 1.0.0-alpha3 * - * @deprecated 1.0.0-alpha4 Use the {@see \PHPCSUtils\Tokens\Collections::namespacedNameTokens()} - * method instead. + * @deprecated 1.0.0-alpha4 Use the {@see Collections::namespacedNameTokens()} method instead. * * @var array => */ @@ -351,11 +353,10 @@ class Collections /** * DEPRECATED: Token types which can be encountered in a parameter type declaration. * - * @since 1.0.0 + * @since 1.0.0-alpha1 * - * @deprecated 1.0.0-alpha4 Use the {@see \PHPCSUtils\Tokens\Collections::parameterTypeTokens()} - * or {@see \PHPCSUtils\Tokens\Collections::parameterTypeTokensBC()} - * method instead. + * @deprecated 1.0.0-alpha4 Use the {@see Collections::parameterTypeTokens()} or + * {@see Collections::parameterTypeTokensBC()} method instead. * * @var array => */ @@ -385,11 +386,10 @@ class Collections /** * DEPRECATED: Token types which can be encountered in a property type declaration. * - * @since 1.0.0 + * @since 1.0.0-alpha1 * - * @deprecated 1.0.0-alpha4 Use the {@see \PHPCSUtils\Tokens\Collections::propertyTypeTokens()} - * or {@see \PHPCSUtils\Tokens\Collections::propertyTypeTokensBC()} - * method instead. + * @deprecated 1.0.0-alpha4 Use the {@see Collections::propertyTypeTokens()} or + * {@see Collections::propertyTypeTokensBC()} method instead. * * @var array => */ @@ -404,11 +404,10 @@ class Collections /** * DEPRECATED: Token types which can be encountered in a return type declaration. * - * @since 1.0.0 + * @since 1.0.0-alpha1 * - * @deprecated 1.0.0-alpha4 Use the {@see \PHPCSUtils\Tokens\Collections::returnTypeTokens()} - * or {@see \PHPCSUtils\Tokens\Collections::returnTypeTokensBC()} - * method instead. + * @deprecated 1.0.0-alpha4 Use the {@see Collections::returnTypeTokens()} or + * {@see Collections::returnTypeTokensBC()} method instead. * * @var array => */ @@ -508,6 +507,12 @@ class Collections * * Note: this is a method, not a property as the `T_FN` token for arrow functions may not exist. * + * @see \PHPCSUtils\Utils\FunctionDeclarations::isArrowFunction() Determine whether an arbitrary token + * is in actual fact an arrow function + * keyword. + * @see \PHPCSUtils\Utils\FunctionDeclarations::getArrowFunctionOpenClose() Get an arrow function's parentheses + * and scope openers and closers. + * * @since 1.0.0-alpha2 * * @return array => @@ -555,7 +560,7 @@ public static function functionCallTokens() * Note: this is a method, not a property as the `T_FN` token for arrow functions may not exist. * * Sister-method to the {@see Collections::functionDeclarationTokensBC()} method. - * This method supports PHPCS 3.5.3 and up. + * This method supports PHPCS 3.5.3 and up. * The {@see Collections::functionDeclarationTokensBC()} method supports PHPCS 2.6.0 and up. * * @see \PHPCSUtils\Tokens\Collections::functionDeclarationTokensBC() Related method (PHPCS 2.6.0+). @@ -596,7 +601,7 @@ public static function functionDeclarationTokens() * declaration or not. * * It is recommended to use the {@see Collections::functionDeclarationTokens()} method instead of - * this method if a standard supports does not need to support PHPCS < 3.5.3. + * this method if a standard does not need to support PHPCS < 3.5.3. * * @see \PHPCSUtils\Tokens\Collections::functionDeclarationTokens() Related method (PHPCS 3.5.3+). * @see \PHPCSUtils\Utils\FunctionDeclarations::isArrowFunction() Arrow function verification. @@ -695,7 +700,7 @@ public static function nameTokens() * * @see \PHPCSUtils\Tokens\Collections::objectOperatorsBC() Related method (PHPCS 2.6.0+). * - * @since 1.0.0-alpha4 + * @since 1.0.0-alpha4 This method replaces the {@see Collections::$objectOperators} property. * * @return array => */ @@ -890,7 +895,7 @@ public static function parameterTypeTokensBC() { $tokens = self::parameterTypeTokens(); - // PHPCS < 4.0; Needed for support of PHPCS < 3.3.0. For PHPCS 3.3.0+ the constant is no longer used. + // PHPCS < 4.0; Needed for support of PHPCS < 3.3.0. As of PHPCS 3.3.0+ the constant is no longer used. if (\defined('T_ARRAY_HINT') === true) { $tokens[\T_ARRAY_HINT] = \T_ARRAY_HINT; } diff --git a/PHPCSUtils/Utils/Arrays.php b/PHPCSUtils/Utils/Arrays.php index af8234b7..84b38b82 100644 --- a/PHPCSUtils/Utils/Arrays.php +++ b/PHPCSUtils/Utils/Arrays.php @@ -71,7 +71,7 @@ public static function isShortArray(File $phpcsFile, $stackPtr) return false; } - // All known tokenizer bugs are in PHPCS versions before 3.5.6. + // All known tokenizer bugs are in PHPCS versions before 3.6.0. $phpcsVersion = Helper::getVersion(); /* diff --git a/PHPCSUtils/Utils/Context.php b/PHPCSUtils/Utils/Context.php index d179c1d6..26b1634d 100644 --- a/PHPCSUtils/Utils/Context.php +++ b/PHPCSUtils/Utils/Context.php @@ -94,7 +94,7 @@ public static function inUnset(File $phpcsFile, $stackPtr) * @param int $stackPtr The position of the token we are checking. * * @return string|false String `'beforeAs'`, `'as'` or `'afterAs'` when the token is within - * a foreach condition. + * a `foreach` condition. * `FALSE` in all other cases, including for parse errors. */ public static function inForeachCondition(File $phpcsFile, $stackPtr) @@ -146,7 +146,7 @@ public static function inForeachCondition(File $phpcsFile, $stackPtr) * @param int $stackPtr The position of the token we are checking. * * @return string|false String `'expr1'`, `'expr2'` or `'expr3'` when the token is within - * a for condition. + * a `for` condition. * `FALSE` in all other cases, including for parse errors. */ public static function inForCondition(File $phpcsFile, $stackPtr) diff --git a/PHPCSUtils/Utils/Lists.php b/PHPCSUtils/Utils/Lists.php index 4c9d229c..9f79de76 100644 --- a/PHPCSUtils/Utils/Lists.php +++ b/PHPCSUtils/Utils/Lists.php @@ -107,9 +107,9 @@ public static function isShortList(File $phpcsFile, $stackPtr) $prevNonEmpty = $phpcsFile->findPrevious(Tokens::$emptyTokens, ($opener - 1), null, true); if ((($prevNonEmpty === 0 - && isset(Collections::phpOpenTags()[$tokens[$prevNonEmpty]['code']]) === true) // Bug #1971. + && isset(Collections::phpOpenTags()[$tokens[$prevNonEmpty]['code']]) === true) // Bug PHPCS#1971. || ($tokens[$prevNonEmpty]['code'] === \T_CLOSE_CURLY_BRACKET - && isset($tokens[$prevNonEmpty]['scope_condition']))) // Bug #1284. + && isset($tokens[$prevNonEmpty]['scope_condition']))) // Bug PHPCS#1284. ) { $closer = $tokens[$opener]['bracket_closer']; $nextNonEmpty = $phpcsFile->findNext(Tokens::$emptyTokens, ($closer + 1), null, true); diff --git a/PHPCSUtils/Utils/Parentheses.php b/PHPCSUtils/Utils/Parentheses.php index e677e994..0d513e62 100644 --- a/PHPCSUtils/Utils/Parentheses.php +++ b/PHPCSUtils/Utils/Parentheses.php @@ -25,7 +25,7 @@ * * @since 1.0.0 * @since 1.0.0-alpha4 Added support for `isset()`, `unset()`, `empty()`, `exit()`, `die()` - * and `eval()`` as parentheses owners to all applicable functions. + * and `eval()` as parentheses owners to all applicable functions. */ class Parentheses { @@ -34,7 +34,7 @@ class Parentheses * Extra tokens which should be considered parentheses owners. * * - `T_LIST` and `T_ANON_CLASS` only became parentheses owners in PHPCS 3.5.0. - * - `T_ISSET`, `T_UNSET`, `T_EMPTY`, `T_EXIT` and `T_EVAL` are not PHPCS native parentheses, + * - `T_ISSET`, `T_UNSET`, `T_EMPTY`, `T_EXIT` and `T_EVAL` are not PHPCS native parentheses * owners, but are considered such for the purposes of this class. * Also {@see https://github.com/squizlabs/PHP_CodeSniffer/issues/3118}. * diff --git a/PHPCSUtils/Utils/PassedParameters.php b/PHPCSUtils/Utils/PassedParameters.php index c5a7cfc8..1e3a7cf0 100644 --- a/PHPCSUtils/Utils/PassedParameters.php +++ b/PHPCSUtils/Utils/PassedParameters.php @@ -55,6 +55,9 @@ class PassedParameters * class instantiation function call when used like `new self()`. * - If passed a `T_ARRAY` or `T_OPEN_SHORT_ARRAY` stack pointer, it will detect * whether the array has values or is empty. + * For purposes of backward-compatibility with older PHPCS versions, `T_OPEN_SQUARE_BRACKET` + * tokens will also be accepted and will be checked whether they are in reality + * a short array opener. * - If passed a `T_ISSET` or `T_UNSET` stack pointer, it will detect whether those * language constructs have "parameters". * @@ -62,9 +65,8 @@ class PassedParameters * @since 1.0.0-alpha4 Added support for PHP 8.0 identifier name tokenization. * * @param \PHP_CodeSniffer\Files\File $phpcsFile The file where this token was found. - * @param int $stackPtr The position of the `T_STRING`, PHP 8.0 identifier - * name token, `T_VARIABLE`, `T_ARRAY`, `T_OPEN_SHORT_ARRAY`, - * `T_ISSET`, or `T_UNSET` token. + * @param int $stackPtr The position of function call name, + * language construct or array open token. * @param true|null $isShortArray Optional. Short-circuit the short array check for * `T_OPEN_SHORT_ARRAY` tokens if it isn't necessary. * Efficiency tweak for when this has already been established, @@ -154,9 +156,8 @@ public static function hasParameters(File $phpcsFile, $stackPtr, $isShortArray = * introducing the new `'name_start'`, `'name_end'` and `'name'` index keys. * * @param \PHP_CodeSniffer\Files\File $phpcsFile The file where this token was found. - * @param int $stackPtr The position of the `T_STRING`, PHP 8.0 identifier - * name token, `T_VARIABLE`, `T_ARRAY`, `T_OPEN_SHORT_ARRAY`, - * `T_ISSET`, or `T_UNSET` token. + * @param int $stackPtr The position of function call name, + * language construct or array open token. * @param int $limit Optional. Limit the parameter retrieval to the first # * parameters/array entries. * @param true|null $isShortArray Optional. Short-circuit the short array check for @@ -349,9 +350,8 @@ public static function getParameters(File $phpcsFile, $stackPtr, $limit = 0, $is * @since 1.0.0 * * @param \PHP_CodeSniffer\Files\File $phpcsFile The file where this token was found. - * @param int $stackPtr The position of the `T_STRING`, PHP 8.0 identifier - * name token, `T_VARIABLE`, `T_ARRAY`, `T_OPEN_SHORT_ARRAY`, - * `T_ISSET`, or `T_UNSET` token. + * @param int $stackPtr The position of function call name, + * language construct or array open token. * @param int $paramOffset The 1-based index position of the parameter to retrieve. * @param string|string[] $paramNames Optional. Either the name of the target parameter * to retrieve as a string or an array of names for the @@ -412,9 +412,8 @@ public static function getParameter(File $phpcsFile, $stackPtr, $paramOffset, $p * @since 1.0.0 * * @param \PHP_CodeSniffer\Files\File $phpcsFile The file where this token was found. - * @param int $stackPtr The position of the `T_STRING`, PHP 8.0 identifier - * name token, `T_VARIABLE`, `T_ARRAY`, `T_OPEN_SHORT_ARRAY`, - * `T_ISSET`, or `T_UNSET` token. + * @param int $stackPtr The position of function call name, + * language construct or array open token. * * @return int * diff --git a/PHPCSUtils/Utils/UseStatements.php b/PHPCSUtils/Utils/UseStatements.php index b4e1b924..00eff45c 100644 --- a/PHPCSUtils/Utils/UseStatements.php +++ b/PHPCSUtils/Utils/UseStatements.php @@ -299,7 +299,12 @@ public static function splitImportUseStatement(File $phpcsFile, $stackPtr) case 'T_NAME_QUALIFIED': case 'T_NAME_FULLY_QUALIFIED': // This would be a parse error, but handle it anyway. - // Only when either at the start of the statement or at the start of a new sub within a group. + /* + * PHPCS 4.x or PHP > 8.0 with PHPCS < 3.5.7. + * + * These tokens can only be encountered when either at the start of the statement + * or at the start of a new sub within a group. + */ if ($start === true && $fixedType === false) { $type = 'name'; }