Skip to content

1.0.0-alpha4 - 2022-10-25

Pre-release
Pre-release
Compare
Choose a tag to compare
@jrfnl jrfnl released this 25 Oct 14:03
· 405 commits to stable since this release
1.0.0-alpha4
37c6da9
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Learn about vigilant mode.

Notes:

  • While still in alpha, some BC-breaks may be introduced. These are clearly indicated in the changelog with the ⚠️ symbol.
  • Until PHPCS 4.x has been released, PHPCSUtils does not formally support it, though an effort is made to keep up with the changes and anticipate potential compatibility issues.
    For testing purposes only, the composer configuration allows for PHPCSUtils to be installed with PHPCS 4.x.

Breaking Changes

Support for PHP_CodeSniffer < 3.7.1 has been dropped after consultation with the principle external standards which depend on PHPCSUtils. #347

This was unfortunately necessary as the incessant additions of new syntaxes since PHP 7.4 made it impossible to continue to support PHPCS < 3.7.1, while still providing reliable results for modern PHP code.

Added

Now support for PHPCS < 3.7.1 has been dropped, this edition adds support to all functionality in PHPCSUtils for new syntaxes and features from PHP 8.0 and 8.1 and preliminary support for PHP 8.2.

This means that support for the following syntaxes/features has been added (or existing support verified/improved):

  • PHP 7.4
    • Array unpacking in array expressions.
  • PHP 8.0
    • The mixed type. #163
    • Union types, including supporting the false and null types. #168, #225
    • Constructor property promotion. #169, #226
    • Nullsafe object operators. #176, #183
    • Namespaced names as single token (cross-version PHPCS 3.x vs 4.x). #205, #206, #207, #208, #209, #210, #211, #212, #213, #217, #241
    • Dereferencing of interpolated text strings.
    • Named arguments in function calls. #235, #243, #383
    • Match expressions. #247, #335, #356
    • Trailing commas in parameter lists and closure use lists.
    • Attributes. #357
  • PHP 8.1
    • Enumerations. #285, #358
    • Explicit octal notation. #293
    • Array unpacking with string keys.
    • never type.
    • Named parameters after argument unpacking. #383
    • First class callables. #362
    • Readonly properties. #363
    • new in initializers.
    • Intersection types. #365
  • PHP 8.2
    • Constants in traits. #366
    • Readonly classes. #367
    • true type. #368
    • null and false as stand-alone types.

Please report any bugs/oversights you encounter!

PHPCS Backcompat

  • BCTokens::magicConstants() as introduced in PHPCS 3.5.6. #172
    The same token array previously already existed in PHPCSUtils as Collections::$magicConstants (which has now been deprecated).

TestUtils

Tokens

Utils

Other

  • PHPCSUtils will now cache the results of (potentially) token walking intensive or processing intensive function calls during a run. #332, #377
    This should significantly improve performance when multiple sniffs call these functions for the same token during a PHPCS run.
    The results of the following functions will now be cached:
    • Arrays::getDoubleArrowPtr()
    • Arrays::isShortArray()
    • FunctionDeclarations::getParameters()
    • Lists::getAssignments()
    • Lists::isShortList()
    • Namespaces::findNamespacePtr()
    • PassedParameters::getParameters()
    • TextStrings::getEndOfCompleteTextString()
    • TextStrings::getStripEmbeds()
    • UseStatements::splitImportUseStatement()

Changed

PHPCS Backcompat

  • All token array methods in the BCTokens class are fully up-to-date with the upstream PHP_CodeSniffer\Util\Tokens properties as per PHPCS master at the time of this release. #327, #347, #360
  • All methods in the BCFile class are fully up-to-date with the upstream PHP_CodeSniffer\Files\File methods as per PHPCS master at the time of this release. #347
  • BCFile::getMethodParameters(): forward compatibility with PHPCS 4.x in which closure use will be a parenthesis owner. #251
  • If a non-existent token array is requested from the BCTokens class, a PHPCSUtils\Exceptions\InvalidTokenArray exception will be thrown. #344
    The PHPCSUtils\Exceptions\InvalidTokenArray exception extends the PHPCS native PHP_CodeSniffer\Exceptions\RuntimeException.
    Previously, an empty array would be returned.

TestUtils

  • UtilityMethodTestCase: all properties contained in the test case class will now always be reset after the tests have run. #325
  • UtilityMethodTestCase::getTargetToken(): when the target token cannot be found, the method will now throw a (catchable) PHPCSUtils\Exceptions\TestTargetNotFound exception instead of failing the test. #248, #371
    If uncaught, this means that the test will be marked as errored instead of failed.
  • UtilityMethodTestCase::getTargetToken(): this method is now static, which allows for it to be used in "set up before class" fixtures. #382. #385

Tokens

  • Collections::functionCallTokens() and Collections::parameterPassingTokens(): now include the T_PARENT token. #328
    This accounts for a change in PHPCS 3.7.0 for how parent in new parent is tokenized.
  • If a non-existent token array is requested from the Collections class, a PHPCSUtils\Exceptions\InvalidTokenArray exception will be thrown. #349
    The PHPCSUtils\Exceptions\InvalidTokenArray exception extends the PHPCS native PHP_CodeSniffer\Exceptions\RuntimeException.

Utils

  • Arrays::isShortArray()/Lists::isShortList(): the underlying logic has been completely refactored for improved accuracy and improved performance. #392
  • FunctionDeclarations::getParameters(): the return array of the method may contain two new keys - property_visibility and visibility_token. #169
    These keys will only be included if constructor property promotion is detected.
  • FunctionDeclarations::getParameters(): forward compatibility with PHPCS 4.x in which closure use will be a parenthesis owner. #251
  • GetTokensAsString: previously the tabReplaced() method was an alias for the normal() method. This has now been reversed. #297
  • Operators::isReference(): forward compatibility with PHPCS 4.x in which closure use will be a parenthesis owner. #195
  • Parentheses: all methods will now recognize isset(), unset(), empty(), exit(), die() and eval() as parentheses owners. #215
    Note: PHPCS natively does not recognize these constructs as parentheses owners, though this may change in the future. See: PHPCS#3118
  • PassedParameters: all methods will now recognize anonymous class instantiations as constructs which can pass parameters. #234
  • PassedParameters::getParameters(): when a named parameter is encountered in a function call, the returned parameter information array for that parameter will now contain the following additional keys: 'name', 'name_token' and the top-level index for the parameter will be set to the parameter 'name' instead of its position. #235, #243, #383
    The existing 'start', 'end', 'raw' and 'clean' keys will contain the same content as before: the information about the parameter value (excluding the name part).
  • PassedParameters::getParameters(): new, optional parameter $limit to allow for limiting the number of parameters/array items to be parsed. #261
    This allows for higher efficiency when retrieving the parameters/array entries, especially for large arrays if only the first few entries need to be examined.
    Use with care on function calls, as this can break support for named parameters!
  • PassedParameters::getParameters(): new, optional parameter $isShortArray to allow for skipping the "is short array" check for predetermined short arrays. #269, #270
    Use judiciously and with extreme care!
  • PassedParameters::getParameter(): new semi-optional $paramNames parameter to allow for retrieving a parameter from a function call using named parameters. #235
    ⚠️ This parameter is required when examining a function call and an exception will be thrown if it was not passed.
    This new $paramNames parameter allows for passing either the parameter name as a string or as an array of strings.
    While a parameter can only have one name, a lot of packages have been, and may still be, reviewing and renaming parameters to more descriptive names to support named parameters in PHP 8.0, so, to allow for supporting multiple versions of packages, different names can be used for the same parameter in a PHP 8.0+ function call and by allowing multiple names to be passed, the method supports this.
  • PassedParameters::getParameter(): efficiency improvement applicable to function calls not using named parameters and arrays. #261, #262
  • PassedParameters::hasParameters(): now allows for the T_PARENT token for new parent() class instantiations. #328
    This accounts for a change in PHPCS 3.7.0 regarding how parent in new parent is tokenized.
  • PassedParameters::hasParameters(): new, optional parameter $isShortArray to allow for skipping the "is short array" check for predetermined short arrays. #269, #270
    Use judiciously and with extreme care!
  • UseStatements::getType(): forward compatibility with PHPCS 4.x in which closure use will be a parenthesis owner. #251

Other

  • The master branch has been renamed to stable. #397
  • ⚠️ All non-abstract classes in this package are now final. #376
  • The parameter names in various function declarations have been changed to not intersect with reserved keywords. #256
    ⚠️ In the unlikely event an external standard using PHPCSUtils would be using function calls with named parameters, the parameter names will need to be updated to match.
  • Composer: The package will now identify itself as a static analysis tool. Thanks @GaryJones! #341
  • Readme/website homepage: the installation instructions have been updated to include information on installing this library and the included Composer PHPCS plugin in combination with Composer >= 2.2. #291, #292
  • Various documentation improvements. #216, #309, #394, #395, #396, #398
  • Various housekeeping and CI maintainance.
    Amongst other things, CI is now run via GitHub Actions (#239), the PHPCSUtils native tests now use the PHPUnit Polyfills package (#277) and the tests are now run against PHP 5.4 - 8.2.

Deprecated

⚠️ Everything which has currently been deprecated, will be removed before the final 1.0.0 version of PHPCSUtils is tagged.

Tokens

Collections class: direct access to the properties in the class is now deprecated for forward-compatibility reasons.
All properties have a replacement which should be used instead, in most cases this will be a method with the same name as the previously used property,

Deprecated Replacement PR Remarks
Collections::$alternativeControlStructureSyntaxTokens Collections::alternativeControlStructureSyntaxes() #311 Mind the change in the name!
Collections::$alternativeControlStructureSyntaxCloserTokens Collections::alternativeControlStructureSyntaxClosers() #311 Mind the change in the name!
Collections::$arrayTokens Collections::arrayTokens() #311
Collections::$arrayTokensBC Collections::arrayTokensBC() #311
Collections::$classModifierKeywords Collections::classModifierKeywords() #311
Collections::$closedScopes Collections::closedScopes() #311
Collections::$controlStructureTokens Collections::controlStructureTokens() #311
Collections::$incrementDecrementOperators Collections::incrementDecrementOperators() #311
Collections::$listTokens Collections::listTokens() #311
Collections::$listTokensBC Collections::listTokensBC() #311
Collections::$magicConstants PHPCSUtils\BackCompat\BCTokens::magicConstants() or PHP_CodeSniffer\Util\Tokens::$magicConstants #311
Collections::$namespaceDeclarationClosers Collections::namespaceDeclarationClosers() #311
Collections::$objectOperators Collections::objectOperators() #176
Collections::$OOCanImplement Collections::ooCanImplement() #311 Mind the case change in the oo prefix!
Collections::$OOCanExtend Collections::ooCanExtend() #311 Mind the case change in the oo prefix!
Collections::$OOConstantScopes Collections::ooConstantScopes() #311 Mind the case change in the oo prefix!
Collections::$OOPropertyScopes Collections::ooPropertyScopes() #311 Mind the case change in the oo prefix!
Collections::$OOHierarchyKeywords Collections::ooHierarchyKeywords() #311 Mind the case change in the oo prefix!
Collections::$OONameTokens Collections::namespacedNameTokens() #202 Mind the change name!
Collections::$parameterTypeTokens Collections::parameterTypeTokens() #168
Collections::$propertyModifierKeywords Collections::propertyModifierKeywords() #311
Collections::$propertyTypeTokens Collections::propertyTypeTokens() #168
Collections::$returnTypeTokens Collections::returnTypeTokens() #168
Collections::$shortArrayTokens Collections::shortArrayTokens() #311
Collections::$shortArrayTokensBC Collections::shortArrayTokensBC() #311
Collections::$shortListTokens Collections::shortListTokens() #311
Collections::$shortListTokensBC Collections::shortListTokensBC() #311
Collections::$textStingStartTokens Collections::textStringStartTokens() #311, #319 Mind the fixed typo in the name!

Additionally, the following methods in the Collections class have been deprecated:

Deprecated Replacement PR
Collections::arrowFunctionTokensBC() Use the T_FN token instead. #347
Collections::functionDeclarationTokensBC() Collections::functionDeclarationTokens() #347
Collections::parameterTypeTokensBC() Collections::parameterTypeTokens() #347
Collections::propertyTypeTokensBC() Collections::propertyTypeTokens() #347
Collections::returnTypeTokensBC() Collections::returnTypeTokens() #347

Utils

  • ControlStructures::getDeclareScopeOpenClose(): this method is no longer needed, check the scope_opener/scope_closer on the T_DECLARE token instead. #347
  • FunctionDeclarations::getArrowFunctionOpenClose(): this method is no longer needed, check the scope_opener/scope_closer etc on the T_FN token instead. #347
  • FunctionDeclarations::isArrowFunction(): this method is no longer needed, use the T_FN token instead. #347

Other

  • The PHPCS23Utils standard, which is no longer needed now support for PHPCS < 3.7.1 has been dropped. #347

Removed

  • Support for PHPCS < 3.7.1. #347

Utils

  • The following constants, which were only intended for internal use, have been removed: #347
    • PHPCSUtils\Utils\Numbers::REGEX_NUMLIT_STRING
    • PHPCSUtils\Utils\Numbers::REGEX_HEX_NUMLIT_STRING
    • PHPCSUtils\Utils\Numbers::UNSUPPORTED_PHPCS_VERSION

Fixed

Abstract Sniffs

  • AbstractArrayDeclarationSniff::getActualArrayKey(): will now handle escaped vars in heredoc array keys better. #379

Fixers

  • SpacesFixer: in a specific new line vs trailing comment situation, the fixer would incorrectly add a stray new line. #229

TestUtils

  • UtilityMethodTestCase::getTargetToken(): will now throw a PHPCSUtils\Exceptions\TestMarkerNotFound exception if the provided test marker comment is not found. #273, #372
    This prevents the method potentially misidentifying the target token.

Tokens

  • Collections::parameterTypeTokens(), Collections::propertyTypeTokens() and Collections::returnTypeTokens(): include the namespace keyword for namespace relative identifier names. #180

Utils

  • Arrays::isShortArray()/Lists::isShortList(): fixed a number of bugs which previously resulted in an incorrect short list/short array determination. #392
  • FunctionDeclarations::getParameters(): will now correctly recognize namespace relative names when used in a parameter type. #180
  • FunctionDeclarations::getProperties(): will now correctly recognize namespace relative names when used in the return type. #180
  • ObjectDeclarations::findExtendedClassName(): will now correctly recognize namespace relative names when used as the extended parent class name. #181
  • ObjectDeclarations::findExtendedInterfaceNames(): will now correctly recognize namespace relative names when used in extended interface names. #181
  • ObjectDeclarations::findImplementedInterfaceNames(): will now correctly recognize namespace relative names when used in implemented interface names. #181
  • ObjectDeclarations::getClassProperties(): will now correctly handle classes declared with both the final as well as the abstract keyword. #252
  • Operators::isReference(): if one parameter in a function declaration was passed by reference, then all T_BITWISE_AND (not intersection type &'s) tokens would be regarded as references. #188
  • Operators::isReference(): the & would not be recognized as a reference for arrow function parameters passed by reference. #192
  • Operators::isUnaryPlusMinus(): a preceding exit, break, continue or arrow function => is now recognized as an indicator that a plus/minus sign is unary. #187, #197
  • Variables::getMemberProperties(): will now correctly recognize namespace relative names when used in a property type. #180

Contributors

GaryJones
Assets 2
Loading