1.0.2 - 2023-03-28

Changed

Tokens

• The Collections::arrayOpenTokensBC(), Collections::arrayTokensBC(), Collections::listOpenTokensBC(), Collections::listTokensBC(), Collections::shortArrayListOpenTokensBC(), Collections::shortArrayTokensBC() and Collections::shortListTokensBC() token arrays will no longer contain the T_OPEN_SQUARE_BRACKET and/or the T_CLOSE_SQUARE_BRACKET token constants if PHP_CodeSniffer 3.7.2 or higher is used. #444
  An upstream bugfix makes it unnecessary to check those tokens for being a short array or short list.
  Sniff which use these token arrays is combination with using the Arrays/Lists classes, should experience a performance boost on PHPCS 3.7.2+ due to this change.

Other

• Minor documentation improvements.
• Various small housekeeping and maintenance updates.

Fixed

Utils

• The Lists::isShortList() method will now correctly recognize a short list nested in a long list as a short list. #446
  Note: this is a parse error in PHP, but the method should still handle this correctly.

1.0.1 - 2023-01-05

Changed

Other

• Composer: The version requirements for the Composer PHPCS plugin have been widened to allow for version 1.0.0. #428
  Please ensure you run composer update phpcsstandards/phpcsutils --with-dependencies to benefit from this.
• Removed the references to pre-1.0.0 QA releases from the docs. #425
• Various small housekeeping and maintainance updates. Thanks @szepeviktor for contributing.

1.0.0 - 2023-01-04

For the full list of features, please see the changelogs of the alpha/rc releases:

• 1.0.0-rc1
• 1.0.0-alpha4
• 1.0.0-alpha3
• 1.0.0-alpha2
• 1.0.0-alpha1

Changed

Other

• Minor documentation improvements.
• Maintainability improvements.

1.0.0-rc1 - 2022-12-27

Added

Tokens

• New Collections::constantModifierKeywords() method. #400
• New Collections::listOpenTokensBC() method. #405

Changed

Utils

• ObjectDeclarations::getClassProperties(): the array return value will now include 'abstract_token', 'final_token', and 'readonly_token' indexes identifying the stack pointers to these keyword, where applicable. If the keyword is not used, the value will be set to false. #401

Other

• Various housekeeping and CI maintainance.

Removed

Everything which was previously deprecated in the 1.0.0-alpha4 release, has now been removed. #410

This includes:

• The PHPCS23Utils standard.
• Collections class: direct access to the properties in the class.
• Collections class: the Collections::arrowFunctionTokensBC(), Collections::functionDeclarationTokensBC(), Collections::parameterTypeTokensBC(), Collections::propertyTypeTokensBC() and Collections::returnTypeTokensBC() methods.
• The ControlStructures::getDeclareScopeOpenClose() method.
• The FunctionDeclarations::getArrowFunctionOpenClose() method.
• The FunctionDeclarations::isArrowFunction() method.

See the changelog for the 1.0.0-alpha4 release for details about replacements for the removed functionality.

Fixed

Utils

• Arrays::getOpenClose(): small efficiency fix. #406
• ControlStructures::hasBody(): correctly identify that a control structure does not have a body - 'has_body' = false -, when the control structure is ended by a PHP close tag. #403
• Lists::getOpenClose(): small efficiency fix. #407

1.0.0-alpha4 - 2022-10-25

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

• New [UtilityMethodTestCase::usesPhp8NameTokens()][UtilityMethodTestCase::usesPhp8NameTokens] method as a helper for tests using token position calculations when testing against both PHPCS 3.x as well as 4.x. [#200], [#217], [#241]

Tokens

• New [PHPCSUtils\Tokens\TokenHelper][TokenHelper] class: Utility functions for working with tokens and token collections. [#304]
  This class initially contains a tokenExists() method to work around potential interference from PHP-Parser also backfilling tokens.
  👉 External standards using a function call to defined() to determine whether a token is available should replace those with a function call to the TokenHelper::tokenExists() method.
• New [Collections::arrayOpenTokensBC()][Collections] method. [#233], [#311]
• New [Collections::functionCallTokens()][Collections] method to retrieve the tokens which can represent function calls and function-call-like language constructs, like class instantiations. [#233]
• New [Collections::nameTokens()][Collections] method to retrieve the tokens which can be used for "names", be it namespace, OO, function or constant names. [#204], [#217]
• New [Collections::namespacedNameTokens()][Collections] method to retrieve the tokens which can be encountered in a fully, partially or unqualified name and in namespace relative names. [#202], [#217]
• New [Collections::parameterPassingTokens()][Collections] method to retrieve the tokens which can be passed to the methods in the [PassedParameters] class. [#233]
• New [Collections::phpOpenTags()][Collections] method. [#254]
• New [Collections::shortArrayListOpenTokensBC()][Collections] method. [#381]

Utils

• New [PHPCSUtils\Utils\Context][Context] class: Utility functions to determine the context in which an arbitrary token is used. [#219]. [#390]
  Initial set of available methods: inEmpty(), inIsset(), inUnset(), inAttribute, inForeachCondition() and inForCondition().
• New [PHPCSUtils\Utils\MessageHelper][MessageHelper] class: Utility functions for creating error/warning messages. [#249], [#391]
  Initial set of available methods: addMessage(), addFixableMessage(), stringToErrorcode() and showEscapeChars().
• New [PHPCSUtils\Utils\PassedParameters::getParameterFromStack()][PassedParameters::getParameterFromStack] efficiency method to retrieve a potentially named function call parameter from a parameter information stack as previously retrieved via PassedParameters::getParameters(). [#235], [#237], [#383]
• New [PHPCSUtils\Utils\TextStrings::getEndOfCompleteTextString()][TextStrings::getEndOfCompleteTextString] method. [#320]
  This method allows to retrieve the stack pointer to the last token within a - potentially multi-line - text string.
  This method compliments the TextStrings::getCompleteTextString() method which will retrieve the contents of the complete text string.
• New [PHPCSUtils\Utils\TextStrings::getEmbeds()][TextStrings::getEmbeds] method to retrieve an array with all variables/expressions as embedded in a text string. [#321]
• New [PHPCSUtils\Utils\TextStrings::stripEmbeds()][TextStrings::stripEmbeds] method to strip all embedded variables/expressions from a text string. [#321]
• New [PHPCSUtils\Utils\TextStrings::getStripEmbeds()][TextStrings::getStripEmbeds] method. [#321]
  This method is public for those rare cases where both the embeds, as well as the text stripped off embeds, is needed.
• New [PHPCSUtils\Utils\UseStatements::mergeImportUseStatements()][UseStatements::mergeImportUseStatements] method. [#196]

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(), ...

1.0.0-alpha3 - 2020-06-29

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, the composer configuration allows for PHPCSUtils to be installed with PHPCS 4.x.
• Until PHP 8.0 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, the composer configuration allows for PHPCSUtils to be installed with PHP 8.

Added

• New [PHPCSUtils\Utils\NamingConventions][NamingConventions] class: Utility functions for working with identifier names (namespace names, class/trait/interface names, function names, variable and constant names). #119
• New PHPCSUtils\BackCompat\Helper::getEncoding() method. #118
• New PHPCSUtils\Utils\ControlStructures::getCaughtExceptions() method. #114, #138
• New PHPCSUtils\Utils\UseStatements::splitAndMergeImportUseStatement() method. #117

PHPCS Backcompat

• BCFile::getMethodProperties(): support for "static" as a return type (PHP 8). #134 PHPCS#2952

TestUtils

• [UtilityMethodTestCase]: new public $phpcsVersion property for use in tests. #107
  Note: if the PHPCS version is needed within a data provider method for a test, Helper::getVersion() still needs to be used as the data providers are run before the setUpBeforeClass()-like methods which set the property.

Tokens

• New [Collections::$incrementDecrementOperators][Collections] property. #130
• New [Collections::$magicConstants][Collections] property. #106
• New [Collections::$objectOperators][Collections] property. #130
• New [Collections::$OOHierarchyKeywords][Collections] property representing the keywords to access properties or methods from inside a class definition, i.e self, parent and static. #115
• New [Collections::$OONameTokens][Collections] property containing tokens which can be part of a partially/fully qualified name when used in inline code. #113
• New [Collections::functionDeclarationTokens()][Collections] method to retrieve the tokens which represent a keyword starting a function declaration. #133
  This method is compatible with PHPCS 3.5.3 and higher.
• New [Collections::functionDeclarationTokensBC()][Collections] method to retrieve the tokens which represent a keyword starting a function declaration (cross-version compatible). #133
  This method is compatible with PHPCS 2.6.0 and higher.
• New [Collections::parameterTypeTokensBC()][Collections] method to retrieve the tokens which need to be recognized for parameter types cross-version. #109
  Use this method when the implementing standard needs to support PHPCS < 3.3.0.
• New [Collections::propertyTypeTokensBC()][Collections] method to retrieve the tokens which need to be recognized for property types cross-version. #109
  Use this method when the implementing standard needs to support PHPCS < 3.3.0.
• New [Collections::returnTypeTokensBC()][Collections] method to retrieve the tokens which need to be recognized for return types cross-version. #109
  Use this method when the implementing standard needs to support PHPCS < 3.5.4.
• Collections::$returnTypeTokens: support for "static" as a return type (PHP 8). #134

Utils

• FunctionDeclarations::getProperties(): support for "static" as a return type (PHP 8). #134

Changed

PHPCS Backcompat

• BCFile::getDeclarationName(): has been made compatible with PHPCS 4.x. #110
• BCFile::getMethodProperties(): has been made compatible with PHPCS 4.x. #109
• BCFile::getMemberProperties(): has been made compatible with PHPCS 4.x. #109
• BCTokens: ⚠️ The visibility of the BCTokens::$phpcsCommentTokensTypes, BCTokens::$ooScopeTokens, BCTokens::$textStringTokens properties has changed from protected to private. #139
• Helper::setConfigData(): has been made compatible with PHPCS 4.x. #137
  A new $config parameter has been added to the method. This parameter is a required parameter when the method is used with PHPCS 4.x.

TestUtils

• [UtilityMethodTestCase]: tests for JS/CSS will now automatically be skipped when run in combination with PHPCS 4.x (which drops JS/CSS support). #111
• Confirmed that the currently available test utils are compatible with PHPUnit 9.x. #103

Tokens

• Collections::$parameterTypeTokens: has been made compatible with PHPCS 4.x. #109
  ⚠️ This removes support for PHPCS < 3.3.0 from the property. Use the [Collections::parameterTypeTokensBC()][Collections] method instead if PHPCS < 3.3.0 needs to be supported.
• Collections::$propertyTypeTokens: has been made compatible with PHPCS 4.x. #109
  ⚠️ This removes support for PHPCS < 3.3.0 from the property. Use the [Collections::propertyTypeTokensBC()][Collections] method instead if PHPCS < 3.3.0 needs to be supported.
• Collections::$returnTypeTokens: has been made compatible with PHPCS 4.x. #109
  ⚠️ This removes support for PHPCS < 3.5.4 from the property. Use the [Collections::returnTypeTokensBC()][Collections] method instead if PHPCS < 3.5.4 needs to be supported.

Utils

• FunctionDeclarations::getArrowFunctionOpenClose(): has been made compatible with PHPCS 4.x. #109
• FunctionDeclarations::getProperties(): has been made compatible with PHPCS 4.x. #109
• ⚠️ Lists::getAssignments(): the return value of the method has been consolidated to be less fiddly to work with. #129
  • ⚠️ The nested_list index key in the return value has been renamed to is_nested_list.
• ObjectDeclarations::getName(): has been made compatible with PHPCS 4.x. #110
• Variables::getMemberProperties(): has been made compatible with PHPCS 4.x. #109

Other

• Composer: PHPCSUtils can now be installed in combination with PHPCS 4.0.x-dev@dev for testing purposes.
• Composer: The version requirements for the [DealerDirect Composer PHPCS plugin] have been widened to allow for version 0.7.0 which supports Composer 2.0.0.
• Readme/website homepage: textual improvements. Props [@GaryJones]. #121
• Readme/website homepage: added additional FAQ question & answers. #157
• The website homepage is now generated using the GitHub Pages gem with Jekyll, making maintenance easier. #141
• Significant improvements to the docblock documentation and by extension the generated API documentation. #145, #146, #147, #148, #149, #150, #151, #152, #153, 154, #155, #156
• Variou...

1.0.0-alpha2 - 2020-02-16

Note: While still in alpha, some BC-breaks may be introduced. These are clearly indicated in the changelog with the ⚠️ symbol.

Added

• New PHPCSUtils\Utils\ControlStructures class: Utility functions for use when examining control structures. #70
• New PHPCSUtils\Utils\FunctionDeclarations::isArrowFunction() method. #77, #79
• New PHPCSUtils\Utils\FunctionDeclarations::getArrowFunctionOpenClose() method. #77, #79

PHPCS Backcompat

• BCFile::isReference(): support for arrow functions returning by reference. #77
• BCFile::getMethodParameters(): support for arrow functions. #77, #79
• BCFile::getMethodProperties(): support for arrow functions. #77, #79, #89
• BCFile::getDeclarationName(): allow functions to be called "fn". #77
• BCFile::findEndOfStatement(): support for arrow functions. #77, #79
• BCFile::findStartOfStatement(): support for arrow functions. #77

Tokens

• New Collections::$alternativeControlStructureSyntaxTokens property. #70
• New Collections::$alternativeControlStructureSyntaxCloserTokens property. #68, #69
• New Collections::$controlStructureTokens property. #70
• New Collections::arrowFunctionTokensBC() method. #79

Utils

• Arrays::getDoubleArrowPtr(): support for arrow functions. #77, #79, #84
• FunctionDeclarations::getParameters(): support for arrow functions. #77, #79
• FunctionDeclarations::getProperties(): support for arrow functions. #77, #79
• Operators::isReference(): support for arrow functions returning by reference. #77
• Parentheses::getOwner(): support for arrow functions. #77
• Parentheses::isOwnerIn(): support for arrow functions. #77, #79

Other

• Documentation website at https://phpcsutils.com/

Changed

PHPCS Backcompat

• BCFile::getCondition(): sync with PHPCS 3.5.4 - added support for new $first parameter. #73

Tokens

• The Collections::$returnTypeTokens property now includes T_ARRAY to allow for supporting arrow functions in PHPCS < 3.5.3. #77

Utils

• ⚠️ Conditions::getCondition(): sync with PHPCS 3.5.4 - renamed the existing $reverse parameter to $first and reversing the meaning of the boolean values, to stay in line with PHPCS itself. #73
• ⚠️ Numbers: the $unsupportedPHPCSVersions property has been replaced with an UNSUPPORTED_PHPCS_VERSION constant.

Other

• Various housekeeping.

1.0.0-alpha1 - 2020-01-23

Initial alpha release containing:

• A PHPCS23Utils standard which can be used to allow an external PHPCS standard to be compatible with both PHPCS 2.x as well as 3.x.
• A PHPCSUtils standard which contains generic utilities which can be used when writing sniffs.
  This standard does not contain any sniffs!
  To use these utilities in PHPCS 3.x, all that is needed is for this package to be installed and registered with PHPCS using installed_paths. If the package is requested via Composer, this will automatically be handled by the DealerDirect Composer PHPCS plugin.
  To use these utilities in PHPCS 2.x, make sure the external standard includes the PHPCS23Utils standard in the ruleset.xml file like so: <rule ref="PHPCS23Utils"/>.

All utilities offered are compatible with PHP_CodeSniffer 2.6.0 up to the latest stable release.

This initial alpha release contains the following utility classes:

Abstract Sniffs

• AbstractArrayDeclarationSniff: to examine array declarations.

Backcompat

• BCFile: Backport of the latest versions of PHPCS native utility functions from the PHP_CodeSniffer\Files\File class to make them available in older PHPCS versions without the bugs and other quirks that the older versions of the native functions had.
• BCTokens: Backport of the latest versions of PHPCS native token arrays from the PHP_CodeSniffer\Util\Tokens class to make them available in older PHPCS versions.
• Helper: Utility methods to retrieve (configuration) information from PHP_CodeSniffer 2.x as well as 3.x.

Fixers

• SpacesFixer: Utility to check and, if necessary, fix the whitespace between two tokens.

TestUtils

• UtilityMethodTestCase: Base class for use when testing utility methods for PHP_CodeSniffer.
  Compatible with both PHPCS 2.x as well as 3.x. Supports PHPUnit 4.x up to 8.x.
  See the usage instructions in the class docblock.

Tokens

• Collections: Collections of related tokens as often used and needed for sniffs.
  These are additional "token groups" to compliment the ones available through the PHPCS native PHP_CodeSniffer\Util\Tokens class.

Utils

• Arrays: Utility functions for use when examining arrays.
• Conditions: Utility functions for use when examining token conditions.
• FunctionDeclarations: Utility functions for use when examining function declaration statements.
• GetTokensAsString: Utility functions to retrieve the content of a set of tokens as a string.
• Lists: Utility functions to retrieve information when working with lists.
• Namespaces: Utility functions for use when examining T_NAMESPACE tokens and to determine the namespace of arbitrary tokens.
• Numbers: Utility functions for working with integer/float tokens.
• ObjectDeclarations: Utility functions for use when examining object declaration statements.
• Operators: Utility functions for use when working with operators.
• Orthography: Utility functions for checking the orthography of arbitrary text strings.
• Parentheses: Utility functions for use when examining parenthesis tokens and arbitrary tokens wrapped in parentheses.
• PassedParameters: Utility functions to retrieve information about parameters passed to function calls, array declarations, isset and unset constructs.
• Scopes: Utility functions for use when examining token scopes.
• TextStrings: Utility functions for working with text string tokens.
• UseStatements: Utility functions for examining use statements.
• Variables: Utility functions for use when examining variables.