New BackCompat\BCFile class - import of utilities from phpcs itself

[jrfnl]

BackCompat\BCFile: import from PHPCS 3.5.0

Import the PHPCS native utility methods from the File class as per PHPCS 3.5.0, as well as any associated unit tests.

These methods will be improved upon further and - in so far possible - made backward-compatible to allow using the most recent PHPCS versions of these utility methods in older PHPCS version as well.

Copyright of the original code here is held by Squizlabs and the respective contributors to PHP_CodeSniffer.

Contributors to the specific code imported have been credited and added as co-authors to this commit.

BackCompat\BCFile: give credit where credit is due

Add author and copyright information for all the imported code.

Note: the names and email addresses used are per the commits made by the contributors to PHP_CodeSniffer, which is information in the public domain.

BackCompat\BCFile: adjust to work within PHPCSUtils

• Adjust namespace.
• Minor adjustments to import use statements.
• Adjust class name.
  The class is named BCFile instead of File on purpose to more easily allow sniffs to use both the PHPCS native File class as well as this class without always having to alias one of the two.
• Adjust method signatures
  • Make all methods static.
  • Add $phpcsFile as first parameter to all methods.
• Adjust code within methods:
  • Add calls to File::getTokens() and use local $tokens variable.
  • Adjust function calls and property access to use $phpcsFile.
  • Remove Utils\ from uses of the Tokens class.

BackCompat\BCFile: adjust to work within PHPCSUtils (unit tests)

Adjust namespace statement, import use statements and the calls to the functions being tested to point to the PHPCSUtils versions of the classes/methods.

BackCompat\BCFile: adjust docs & CS

Minimal adjustments to the docs and code style to make the class fit into PHPCSUtils properly.

• Add standard PHPCSUtils file docblock info.
• Add class docblock.
• Add function @since tags for PHPCSUtils.
• Remove extraneous blank lines between methods.
• Remove function, class, control structure //end comments.

BackCompat\BCFile: adjust docs & CS (unit tests)

Minimal adjustments to the docs and code style to make the classes fit into PHPCSUtils properly.

• Add standard PHPCSUtils file docblock info.
• Add class docblock.
• Remove extraneous blank lines between methods.
• Remove function and class //end comments.

BackCompat\BCFile: document work-arounds added

Add documentation about which Tokenizer changes are being accounted for in the utility methods in this class.

Method specific changes

BCFile::getDeclarationName()

• Improve documentation.
• Add changelog for PHPCS changes between PHPCS 2.6.0 and now.

BCFile::getMethodParameters()

• Add changelog for PHPCS changes between PHPCS 2.6.0 and now.
• Re-order unit tests.
  List the unit tests in the order they are run.
• Make the existing unit tests feature complete. [1]
  Test the correct determination of the token position for the various ...token index keys.
• Make the existing unit tests feature complete. [2]
  • Test the situations in which the method returns an empty array.
  • Add a significant number of additional unit tests:
    • Cover all situations this method handles, i.e. test closures and closure use statements.
    • Test variadic functions.
    • Test handling of all type declarations supported by PHP.
    • Test handling of the PHPCS 3.2.0+ ignore annotations.
    • Test (document) the behaviour of the function with fully qualified class names as type declaration, including when such a type declaration is interlaced with comments and whitespace.
    • Verify that a ternary in a default expression will not be confused with nullability.
  • Test the Exceptions being thrown by the method.
• Fix "type_hint_end_token" bleed through.
  Fixed a bug where a subsequent parameter without type declaration would get the type_hint_end_token from the end of the type declaration from a previous parameter.
  This bug fix is included in PHPCS 3.5.3 upstream.
  Ref: File::getMethodParameters() setting typeHintEndToken for vars with no type hint squizlabs/PHP_CodeSniffer#2685
• Fix compatibility with PHPCS < 3.3.0.
  • Between PHPCS 2.4.0 and 3.2.3, array type declaration were tokenized as T_ARRAY_HINT.
    This has been changed to "normalized" tokenization in PHPCS 3.3.0.
• Fix compatibility with PHPCS < 2.8.0.
  • The T_NULLABLE token was only introduced in PHPCS 2.8.0, so the constant may not exist.
    For PHPCS < 2.8.0, the token will be T_INLINE_THEN.

BCFile::getMethodProperties()

• Improve documentation.
• Add changelog for PHPCS changes between PHPCS 2.6.0 and now.
• Make the existing unit tests feature complete.
  • Test the correct determination of the token position for the return_type_token index key.
  • Test the Exception being thrown by the method.
  • Test recognition of array return type declaration with a code sample which will be incorrectly tokenized in PHPCS < 2.8.0.
• Fix compatibility with PHPCS < 3.3.0.
  • Between PHPCS 2.4.0 and 3.2.3, return types were tokenized as T_RETURN_TYPE.
    This has been changed to "normalized" tokenization in PHPCS 3.3.0.
  • A bug existed with the tokenization of return types to T_RETURN_TYPE which would cause array return type declarations to be tokenized as T_ARRAY_HINT in certain circumstances.
    This bug was fixed in PHPCS 2.8.0.
  • The T_NULLABLE token was only introduced in PHPCS 2.8.0, so the constant may not exist.
    For PHPCS < 2.8.0, the token will be T_INLINE_THEN.

BCFile::getMemberProperties()

• Improve documentation.
• Add changelog for PHPCS changes between PHPCS 2.6.0 and now.
• Make the existing unit tests feature complete.
  • Test the correct determination of the token position for the type_token and the type_end_token index keys.
  • Test handling of the PHPCS 3.2.0+ ignore annotations.
• Make the existing unit tests compatible with PHPUnit 8+.
• Fix compatibility with PHPCS < 3.5.0.
  • The T_NULLABLE token was only introduced in PHPCS 2.8.0, so the constant may not exist.
  • Prior to PHPCS 3.5.0, even when the T_NULLABLE token does exist, the nullable indicator for typed property declarations would not be corrected to T_NULLABLE by the Tokenizer and would still be a T_INLINE_THEN token.
    See: PHPCS issue PHP 7.4: tokenizing of typed properties squizlabs/PHP_CodeSniffer#2413
  • Prior to PHPCS 3.3.0, the array keyword when not used to declare an array would be tokenized as T_ARRAY_HINT.
    This has been changed to "normalized" tokenization in PHPCS 3.3.0 and it will now be tokenized as a T_STRING.

BCFile::getClassProperties()

• Improve documentation.
• Add changelog for PHPCS changes between PHPCS 2.6.0 and now.

BCFile::isReference()

• Improve documentation.
• Add changelog for PHPCS changes between PHPCS 2.6.0 and now.
• Fix minor parse errors in the unit test case file.
• Fix test documentation.
• Make the existing unit tests feature complete.
  • Test passing an unexpected token.
  • Test assignment using null coalesce equals.
• Add tests for list assignments by reference (PHP 7.3+).
• Fix compatibility with PHPCS 2.8.1.
  ... as while the T_COALESCE_EQUAL was introduced in PHPCS 2.8.1, it wasn't added to the Tokens::$assignmentTokens array until PHPCS 2.9.0.
• Fix code coverage not correctly registering.

BCFile::getTokensAsString()

• Improve documentation.
• Add changelog for PHPCS changes between PHPCS 2.6.0 and now.

BCFile::findStartOfStatement()

• Add changelog for PHPCS changes between PHPCS 2.6.0 and now.

BCFile::findEndOfStatement()

• Add changelog for PHPCS changes between PHPCS 2.6.0 and now.

BCFile::hasCondition()

• Add changelog for PHPCS changes between PHPCS 2.6.0 and now.

BCFile::getCondition()

• Improve documentation.
• Add changelog for PHPCS changes between PHPCS 2.6.0 and now.

BCFile::findExtendedClassName()

• Improve documentation.
• Add changelog for PHPCS changes between PHPCS 2.6.0 and now.
• Make the existing unit tests feature complete.
  • Test support of anonymous classes.
  • Test the situations in which the method returns false.
  • Confirm non-support of multi-extended interfaces.

BCFile::findImplementedInterfaceNames()

• Improve documentation.
• Add changelog for PHPCS changes between PHPCS 2.6.0 and now.
• Make the existing unit tests feature complete.
  • Test support of anonymous classes.
  • Test handling of the PHPCS 3.2.0+ ignore annotations.
  • Test the situations in which the method returns false.