Added

Compatibility with the new PHP_CodeSniffer 4.x branch in anticipation of the PHP_CodeSniffer 4.0 release. #674, #679
PHPCSUtils should now be fully compatible with PHP_CodeSniffer 4.0 (again). If you still find an issue, please report it.

PHPCS BackCompat

• BCFile::findExtendedClassName(): sync with PHPCS 4.0.0 - support for namespace relative names when used as the extended parent class name. #674
• BCFile::findImplementedInterfaceNames(): sync with PHPCS 4.0.0 - support for namespace relative names when used in implemented interface names. #674
• BCFile::getMemberProperties(): sync with PHPCS 3.12.0 - support for PHP 8.4 final properties. Thanks @DanielEScherzer! #646
• BCFile::getMemberProperties(): sync with PHPCS 3.13.1 - support for PHP 8.4 asymmetric visibility. #677
• BCFile::getMemberProperties(): sync with PHPCS 4.0.0. #674
  • Add support for PHP 8.4 properties in interfaces.
  • Removed parse error warning.
• BCFile::getMethodParameters(): sync with PHPCS 3.13.1 - support for PHP 8.4 asymmetric visibility. #677
• BCFile::findStartOfStatement(): sync with PHPCS 3.12.1 - support for goto as a switch - case terminating statement. #661
• BCTokens::nameTokens() as introduced in PHPCS 4.0.0. #674
  The same token array previously already existed in PHPCSUtils as Collections::nameTokens().
• BCTokens::functionNameTokens(): sync with PHPCS 4.0.0 - added the T_ANON_CLASS token. #674
• BCTokens::parenthesisOpeners(): sync with PHPCS 4.0.0 - added the T_USE, T_ISSET, T_UNSET, T_EMPTY, T_EVAL and T_EXIT tokens. #674
  Note: While T_USE, T_ISSET, T_UNSET, T_EMPTY, T_EVAL and T_EXIT will be included in the return value for this method,
  the associated parentheses will not have the 'parenthesis_owner' index set unless PHPCS 4.0.0 is used.
  Use the Parentheses::getOwner() or the Parentheses::hasOwner() methods if you need to check
  whether any of these tokens are a parentheses owner. The methods in the Parentheses class are PHPCS cross-version compatible.

TestUtils

• New PHPCSUtils\TestUtils\ConfigDouble class as a lightweight and more stable alternative to directly using the PHPCS native Config class in tests. #550, #612
  Props to @fredden for helping me find and fix a bug in this feature before it was released.
• New PHPCSUtils\TestUtils\RulesetDouble class which allows for creating a Ruleset object without registering any sniffs. #674
  This allows for the PHPCSUtils\TestUtils\UtilityMethodTestCase class to be cross-version compatible with both PHP_CodeSniffer 3.x as well as 4.x.
• New PHPCSUtils\TestUtils\UtilityMethodTestCase::parseFile() method to allow for on-demand tokenizing of a (secondary) test case file. #591, #610
  This method is intended for tests which need to use multiple test case files, like, for example, tests which need to verify that a utility resets a $fileName property on seeing another file.
• New PHPCSUtils\TestUtils\UtilityMethodTestCase::testTestMarkersAreUnique() and PHPCSUtils\TestUtils\UtilityMethodTestCase::assertTestMarkersAreUnique() methods which automatically check that code sample files used with this TestCase do not contain duplicate test case markers. #642
  If needs be, the test method can be disabled by overloading it (discouraged). If a test uses multiple test case/code sample files, the assertion method can be called directly.

Tokens

• New Collections::constantTypeTokens() method to support PHP 8.3 typed class constants. #562
• New Collections::ternaryOperators() method. #549
• T_EXIT to the Collections::functionCallTokens() and Collections::parameterPassingTokens() in light of the PHP 8.4 "exit as function" change. #618
• The PHP 8.4 asymmetric visibility tokens have been added to the Collections::propertyModifierKeywords() method. #653
• T_INTERFACE has been added to the Collections::ooPropertyScopes() method for PHP 8.4 interface properties support. #674

Utils

• New PHPCSUtils\Utils\Constants class: Utility functions to examine (class) constants. #562
  Initially available method: getProperties() to retrieve an array of information about an OO constant declaration.
• New PHPCSUtils\Utils\FileInfo class: Utility functions to check characteristics of the file under scan. #572
  Initial set of available methods: hasByteOrderMark() and hasSheBang().
• New PHPCSUtils\Utils\FilePath class: Utility functions for handling and comparing file paths. #593
  Initial set of available methods: getName() to retrieve the normalized path for the current file, isStdin(), normalizeAbsolutePath(), normalizeDirectorySeparators(), trailingSlashIt() and startsWith().
• New PHPCSUtils\Utils\TypeString class: Utility functions for analysing typestrings as retrieved via the various available getParameters()/getProperties() methods. #588
  Initial set of available methods: getKeywordTypes(), isKeyword(), normalizeCase(), isSingular(), isNullable(), isUnion(), isIntersection(), isDNF(), toArray(), toArrayUnique(), filterKeywordTypes() and filterOOTypes().
  Note: The is*() methods will not check if the type string provided is valid, as doing so would inhibit what sniffs can flag. The is*() methods will only look at the form of the type string to determine if it could be valid for a certain type.
• New PHPCSUtils\Utils\ObjectDeclarations::getDeclaredConstants(), PHPCSUtils\Utils\ObjectDeclarations::getDeclaredEnumCases(), PHPCSUtils\Utils\ObjectDeclarations::getDeclaredProperties() and PHPCSUtils\Utils\ObjectDeclarations::getDeclaredMethods() utility methods. #592
  These methods will each return an array with the name of the constant/case/property/method as the key and the typical stack pointer needed for further processing.
  The retrieval of this information is highly optimized for performance. If a sniff needs to search for a named constant/enum case/property/method in an OO structure, in most cases, these methods should be the recommended way for finding the declaration, instead of the sniff attempting to do this itself.
  Mind: the return value of the getDeclaredProperties() method includes constructor promoted properties. Passing the stack pointer of constructor promoted properties onto a call to the Variables::getMemberProperties() method, however, is currently not supported.
• FunctionDeclarations::getParameters(): support for PHP 8.4 asymmetric visibility. #677
• Variables::getMemberProperties(): support for PHP 8.4 final properties. Thanks @DanielEScherzer! #646
• Variables::getMemberProperties(): support for PHP 8.4 asymmetric visibility. #677

Changed

• The exceptions thrown by PHPCSUtils native utilities have been made more modular and more specific. #598, #599, #600
  • Passing a parameter of the wrong type will now result in a PHPCSUtils\Exceptions\TypeError being thrown.
  • Passing a parameter of the correct type, but with an invalid value, like an empty string when only non-empty strings are expected/accepted, will now result in a PHPCSUtils\Exceptions\ValueError being thrown.
  • Passing a (positive) integer stack pointer, which doesn't exist in the token stack of the current file, will now result in a PHPCSUtils\Exceptions\OutOfBoundsStackPtr being thrown.
  • Passing a stack pointer to a token which is not within the range of token types which is accepted by the method, will now result in a PHPCSUtils\Exceptions\UnexpectedTokenType being thrown.
  • Logic errors will now result in a PHPCSUtils\Exceptions\LogicException being thrown.
    This can occur, for instance, when a method takes a $start and $end parameter and the $end pointer is before the $start pointer.
  • Missing, conditionally required, parameters, will now result in a PHPCSUtils\Exceptions\MissingArgumentError being thrown.
  • Generic errors will now result in a PHPCSUtils\Exceptions\RuntimeException being thrown.
  • Previously the PHPCS native PHP_CodeSniffer\Exceptions\RuntimeException was used for all these exceptions.
    Catching the PHPCS native RuntimeException will still catch the new exceptions, but it is strongly recommended to be more selective when catching exceptions to prevent accidentally hiding errors in sniffs.
  • Also note that the PHPCSUtils native utilities now include more and stricter type checking to help surface bugs in sniffs.

Abstract Sniffs

• The AbstractArrayDeclarationSniff::process() method will no longer hide exceptions about a non-integer or non-existent stack pointer being passed. #600
• The AbstractArrayDeclarationSniff::processArray() method will no longer hide exceptions about non-integer or non-existent stack pointers being passed. #600

PHPCS BackCompat

*...

Added

PHPCS BackCompat

• BCFile::getMemberProperties(): sync with PHPCS 3.10.0 - support for PHP 8.2 DNF types. #604
• BCFile::getMethodProperties(): sync with PHPCS 3.10.0 - support for PHP 8.2 DNF types. #604
• BCFile::getMethodParameters(): sync with PHPCS 3.10.0 - support for PHP 8.2 DNF types. #604

Utils

• FunctionDeclarations::getParameters(): support for PHP 8.2 DNF types. #604
• FunctionDeclarations::getProperties(): support for PHP 8.2 DNF types. #604
• Variables::getMemberProperties(): support for PHP 8.2 DNF types. #604

Changed

Tokens

• Collections::parameterTypeTokens(), Collections::propertyTypeTokens() and Collections::returnTypeTokens(): now include the new T_TYPE_OPEN_PARENTHESIS and T_TYPE_CLOSE_PARENTHESIS tokens for PHP 8.2 DNF type support. #604

Utils

• ControlStructures::getCaughtExceptions(): will now silently ignore parse errors in the code under scan which prevent the method from analyzing a catch statement. #594
  The method will now return an empty array instead of throwing a PHP_CodeSniffer\Exceptions\RuntimeException.

Other

• Dropped support for PHP_CodeSniffer < 3.10.0. #603
  Please ensure you run composer update phpcsstandards/phpcsutils --with-dependencies to benefit from this.
• Various housekeeping and documentation improvements.

Fixed

Utils

• UseStatements::splitImportUseStatement(): the values in the return array will now never include a leading backslash. #590
  Previously the behaviour around import use statements declared with a leading backslash was undefined and the backslash would be included in the return value.

Changed

Other

• Various housekeeping and documentation improvements. Includes a contribution from @fredden.

Fixed

PHPCS BackCompat

• BCFile::getMethodProperties(): small performance improvement & more defensive coding, in line with same fix in PHPCS 3.9.2. #573

Utils

• FunctionDeclarations::getProperties(): small performance improvement & more defensive coding, in line with same fix in PHPCS 3.9.2. #573

Changed

Other

• Dropped support for PHP_CodeSniffer < 3.9.0. #561
  Please ensure you run composer update phpcsstandards/phpcsutils --with-dependencies to benefit from this.
• Various housekeeping and documentation improvements.

Deprecated

Utils

• NamingConventions::AZ_UPPER constant. #563
• NamingConventions::AZ_LOWER constant. #563

Fixed

PHPCS BackCompat

• BackCompat\Helper::getEncoding(): PHP 8.4 deprecation notice. #568
• BackCompat\Helper::ignoreAnnotations(): PHP 8.4 deprecation notice. #568

Added

PHPCS BackCompat

• BCFile::getMemberProperties(): sync with PHPCS 3.8.0 - support for PHP 8.2 true type. #524
• BCFile::getMethodProperties(): sync with PHPCS 3.8.0 - support for PHP 8.2 true type. #524
• BCFile::getMethodParameters(): sync with PHPCS 3.8.0 - support for PHP 8.2 true type. #524

Changed

TestUtils

• Significant performance improvement for the UtilityMethodTestCase. #525

Other

• Dropped support for PHP_CodeSniffer < 3.8.0. #523
  Please ensure you run composer update phpcsstandards/phpcsutils --with-dependencies to benefit from this.
• Small improvements to the documentation website generation. Includes a contribution from @fredden.
• Various housekeeping and documentation improvements. Includes a contribution from @fredden.

Changed

PHPCS BackCompat

• BCFile::getDeclarationName(): sync with PHPCS 3.8.0 - support for functions called self, parent or static which return by reference. #494

Other

• Various housekeeping and minor documentation improvements.

Fixed

Fixers

• The SpacesFixer will no longer throw an (incorrect) exception when the second pointer passed is a comment token and this comment token is the last content in a file. #493

Changed

Other

• Various housekeeping and maintenance updates, including making the test suite compatible with PHPUnit 10.

Fixed

Utils

• The Arrays::getDoubleArrowPtr() method could previously get confused over a double arrow in a keyed list used as an array value. #485

Changed

PHPCS BackCompat

• BCFile::getClassProperties(): sync with PHPCS 3.8.0 - support for PHP 8.2 readonly classes. #470
• BCFile::getMethodParameters(): sync with PHPCS 3.8.0 - support for constructor property promotion with readonly properties without explicit visibility. #472

Utils

• The results of the following methods will now (also) be cached for improved performance when multiple sniffs call these functions for the same token during a PHPCS run. #464, #466
  • FunctionDeclarations::getProperties()
  • Variables::getMemberProperties()
• Additionally, the results of the UseStatements::splitImportUseStatement() method will be cached more often and the cache checked earlier. #467
• The return value of the ControlStructures::getCaughtExceptions() method will no longer contain "empty" entries for catch statements without a named exception. It will return an empty array instead. #474

Other

• Various small housekeeping and maintenance updates.

Fixed

Abstract Sniffs

• AbstractArrayDeclarationSniff: fixed a potential "Trying to access array offset on value of type bool" PHP notice. #476
• AbstractArrayDeclarationSniff: the abstract will no longer trigger potentially available magic __get()/__set() etc methods. #477

Fixed

Utils

• The Lists::getAssignments() method could previously get confused over exotic list keys. Fixed now. #459

Changed

Other

• Minor documentation improvements.

Fixed

Utils

• The FunctionDeclarations::getParameters() method will now correctly handle constructor promoted properties with readonly, but without explicit visibility set. #456