wishthis/vendor/phpcsstandards/phpcsextra/CHANGELOG.md

Change Log for the PHPCSExtra standard for PHP CodeSniffer

All notable changes to this project will be documented in this file.

This projects adheres to Keep a CHANGELOG and uses Semantic Versioning.

Legend: 🔧 = Includes auto-fixer. 📊 = Includes metrics. 📚 = Includes CLI documentation.

Unreleased

Nothing yet.

1.1.1 - 2023-08-26

Changed

Modernize

• Modernize.FunctionCalls.Dirname: the sniff will now respect a potentially set php_version configuration option and only report on modernizations which are possible on the configured php_version. #261 If the php_version is not set, the sniff will continue to report on all modernization options.

Other

• Various documentation improvements. Props in part to @szepeviktor.
• Improved defensive coding in select places.
• Various housekeeping.

1.1.0 - 2023-07-19

Added

Universal

• 🔧 📚 New Universal.CodeAnalysis.NoEchoSprintf sniff to detect use of the inefficient echo [v]sprintf(...); combi and recommends using [v]printf() instead. #242
• 📊 📚 New Universal.FunctionDeclarations.NoLongClosures sniff to detect "long" closures and recommend using a named function instead. #240 The sniff offers the following properties to influence its behaviour: recommendedLines (defaults to 5), maxLines (defaults to 8), ignoreCommentLines (defaults to true) and ignoreEmptyLines (defaults to true).
• 🔧 📊 📚 New Universal.FunctionDeclarations.RequireFinalMethodsInTraits sniff to enforce non-private, non-abstract methods in traits to be declared as final. #243, #245 There is a separate NonFinalMagicMethodFound error code for magic methods to allow those to be excluded from the check.
• 🔧 📊 📚 New Universal.UseStatements.DisallowMixedGroupUse sniff to disallow group use statements which import a combination of namespace/OO construct, functions and/or constants in one statement. #241, #246 Note: the fixer will use a semi-standardized format for group use statements. If there are more specific requirements for the formatting of group use statements, the ruleset configurator should ensure that additional sniffs are included in the ruleset to enforce the required format.
• 🔧 📊 📚 New Universal.UseStatements.KeywordSpacing sniff to enforce the use of a single space after the use, function, const keywords and both before and after the as keyword in import use statements. #247 The sniff has modular error codes to allow for disabling individual checks.
• 🔧 📚 New Universal.UseStatements.NoUselessAliases sniff to detect useless aliases (aliasing something to its original name) in import use statements. #244 Note: as OO and function names in PHP are case-insensitive, aliasing to the same name, using a different case is also considered useless.
• 🔧 📊 📚 New Universal.WhiteSpace.CommaSpacing sniff to enforce that there is no space before a comma and exactly one space, or a new line, after a comma. #254 Additionally, the sniff also enforces that the comma should follow the code and not be placed after a trailing comment. The sniff has modular error codes to allow for disabling individual checks and checks in certain contexts. The sniff will respect a potentially set php_version configuration option when deciding how to handle the spacing after a heredoc/nowdoc closer.

Changed

Universal

• Minor performance improvements for the Universal.Arrays.DuplicateArrayKey and the Universal.CodeAnalysis.ConstructorDestructorReturn sniffs. #251, #252

Other

• Composer: The minimum PHPCSUtils requirement has been updated to ^1.0.8 (was ^1.0.6). #249, #254
• Various housekeeping.

1.0.4 - 2023-06-18

Changed

Other

• Composer: The minimum PHPCSUtils requirement has been updated to ^1.0.6 (was ^1.0.0). #237
• Various housekeeping.

Fixed

Universal

• Universal.Constants.LowercaseClassResolutionKeyword: prevent false positives for function calls to methods called class. #226

1.0.3 - 2023-03-28

Changed

Universal

• Universal.WhiteSpace.DisallowInlineTabs: significant performance improvement. #216, #217

Other

• Various housekeeping.

Fixed

Modernize

• Modernize.FunctionCalls.Dirname: prevent false positives for attribute classes called dirname. #211, #213

1.0.2 - 2023-01-10

Changed

Universal

• Universal.CodeAnalysis.ConstructorDestructorReturn: the sniff will now respect a potentially set php_version configuration option and only report on PHP4-style constructors when the php_version is below '80000'. Thanks @anomiex for reporting! #207, #208

1.0.1 - 2023-01-05

Fixed

Universal

• Universal.CodeAnalysis.ConstructorDestructorReturn: fixed false positive for return statements in nested functions/closures declared within constructor/destructor methods. Thanks @anomiex for reporting! #201, #202

1.0.0 - 2023-01-04

⚠️ Important: this package now requires PHPCSUtils 1.0.0. Please make sure you use --with-[all-]dependencies when running composer update. ❗

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

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

Changed

Other

• Updated various sniffs to take advantage of PHPCSUtils 1.0.0(-rc1). #193, #194, #195
• Minor documentation improvements.
• Various housekeeping.

Fixed

Modernize

• Modernize.FunctionCalls.Dirname: the sniff will now correctly recognize magic constants in a case-insensitive manner. #187

1.0.0-RC1 - 2022-12-07

⚠️ Important: this package now requires PHPCSUtils 1.0.0-alpha4. Please make sure you use --with-[all-]dependencies when running composer update. ❗

Added

Modernize

• This is a new standard with one sniff to start with.
• 🔧 📚 New Modernize.FunctionCalls.Dirname sniff to detect and auto-fix two typical code modernizations which can be made related to the dirname() function. #172

Universal

• 🔧 📊 📚 New Universal.Classes.DisallowAnonClassParentheses sniff to disallow the use of parentheses when declaring an anonymous class without passing parameters. #76, #162
• 🔧 📊 📚 New Universal.Classes.RequireAnonClassParentheses sniff to require the use of parentheses when declaring an anonymous class, whether parameters are passed or not. #76, #166
• 🔧 📊 📚 New Universal.Classes.DisallowFinalClass sniff to disallow classes being declared final. #108, #114, #148, #163
• 🔧 📊 📚 New Universal.Classes.RequireFinalClass sniff to require all non-abstract classes to be declared final. #109, #148, #164 Warning: the auto-fixer for this sniff may have unintended side-effects for applications and should be used with care! This is considered a risky fixer.
• 🔧 📊 📚 New Universal.Classes.ModifierKeywordOrder sniff to standardize the modifier keyword order for class declarations. #142 The sniff offers an order property to specify the preferred order.
• 🔧 📚 New Universal.CodeAnalysis.ConstructorDestructorReturn sniff to verify that class constructor/destructor methods 1) do not have a return type declaration and 2) do not return a value. #137, #140, #146 Inspired by @derickr.
• 🔧 📚 New Universal.CodeAnalysis.ForeachUniqueAssignment sniff to detect foreach control structures which use the same variable for both the key as well as the value assignment as this will lead to unexpected - and most likely unintended - behaviour. #110, #175 The fixer will maintain the existing behaviour of the code. Mind: this may not be the intended behaviour.
• 🔧 📚 New Universal.CodeAnalysis.StaticInFinalClass sniff to detect using static instead of self in OO constructs which are final. #116, #180 The sniff has modular error codes to allow for making exceptions based on the type of use for static.
• 🔧 📊 📚 New Universal.Constants.LowercaseClassResolutionKeyword sniff to enforce that the class keyword when used for class name resolution, i.e. ::class, is in lowercase. #72
• 🔧 📊 📚 New Universal.Constants.ModifierKeywordOrder sniff to standardize the modifier keyword order for OO constant declarations. #143 The sniff offers an order property to specify the preferred order.
• 🔧 📚 New Universal.ControlStructures.DisallowLonelyIf sniff to disallow if statements as the only statement in an else block. #85, #168, #169 Inspired by the ESLint "no lonely if" rule. Note: This sniff will not fix the indentation of the "inner" code. It is strongly recommended to run this sniff together with the Generic.WhiteSpace.ScopeIndent sniff to get the correct indentation.
• 📊 📚 New Universal.Files.SeparateFunctionsFromOO sniff to enforce that a file should either declare (global/namespaced) functions or declare OO structures, but not both. #95, #170, #171 Nested function declarations, i.e. functions declared within a function/method will be disregarded for the purposes of this sniff. The same goes for anonymous classes, closures and arrow functions.
• 📚 New Universal.NamingConventions.NoReservedKeywordParameterNames sniff to verify that function parameters do not use reserved keywords as names, as this can quickly become confusing when people use them in function calls using named parameters. #80, #81, #106, #107, #173 The sniff has modular error codes to allow for making exceptions for specific keywords.
• 🔧 📊 📚 New Universal.Operators.TypeSeparatorSpacing sniff to enforce no spaces around union type and intersection type separators. #117
• 🔧 📚 New Universal.PHP.OneStatementInShortEchoTag sniff to disallow short open echo tags <?= containing more than one PHP statement. #89, #147, #165
• 🔧 📊 📚 New Universal.WhiteSpace.AnonClassKeywordSpacing sniff to standardize the amount of spacing between the class keyword and the open parenthesis (if any) for anonymous class declarations. #120 The sniff offers a spacing property to set the amount of spaces the sniff should check for.
• 🔧 📚 New Universal.WhiteSpace.PrecisionAlignment sniff to enforce indentation to always be a multiple of a tabstop, i.e. disallow precision alignment. #119, #122, #123, #124 Note:
  • This sniff does not concern itself with tabs versus spaces. It is recommended to use the sniff in combination with the PHPCS native Generic.WhiteSpace.DisallowTabIndent or the Generic.WhiteSpace.DisallowSpaceIndent sniff.
  • When using this sniff with tab-based standards, please ensure that the tab-width is set and either don't set the $indent property or set it to the tab-width (or a multiple thereof).
  • The fixer works based on "best guess" and may not always result in the desired indentation. Combine this sniff with the Generic.WhiteSpace.ScopeIndent sniff for more precise indentation fixes.
  • The behaviour of the sniff is customizable via the following properties:
    • indent: the indent used for the codebase.
    • ignoreAlignmentBefore: allows for providing a list of token names for which (preceding) precision alignment should be ignored.
    • ignoreBlankLines: whether or not potential trailing whitespace on otherwise blank lines should be examined or ignored.

Changed

Universal

• Universal.Arrays.DisallowShortArraySyntax: the sniff will now record metrics about long vs short array usage. #154
• Universal.Arrays.DuplicateArrayKey: where relevant, the sniff will now make a distinction between keys which will be duplicate in all PHP version and (numeric) keys which will only be a duplicate key in PHP < 8.0 or PHP >= 8.0. #177, #178 If a php_version configuration option has been passed to PHPCS, it will be respected by the sniff and only report duplicate keys for the configured PHP version.
• Universal.ControlStructures.DisallowAlternativeSyntax: the sniff will now also record a metric when single-line (no body) control structures are encountered. #158
• Universal.ControlStructures.DisallowAlternativeSyntax: the error message thrown by the sniff is now more descriptive. #159
• Universal.ControlStructures.DisallowAlternativeSyntax: metrics will no longer be recorded for elseif and else keywords, but only on the if keyword as the type of syntax used has to be the same for the whole "chain". #161
• Universal.Lists.DisallowLongListSyntax: the sniff will no longer record (incomplete) metrics about long vs short list usage. #155
• Universal.Lists.DisallowShortListSyntax: the sniff will now record (complete) metrics about long vs short list usage. #155
• Universal.OOStructures.AlphabeticExtendsImplements: documented support for enum ... implements. #150
• Universal.UseStatements.DisallowUseClass: updated error message and metric name to take PHP 8.1 enums into account. #149
• Universal.UseStatements.NoLeadingBackslash: the sniff will now also flag and auto-fix leading backslashes in group use statements. #167

Other

• Updated the sniffs for compatibility with PHPCSUtils 1.0.0-alpha4. #134
• Updated the sniffs to correctly handle PHP 8.0/8.1/8.2 features whenever relevant.
• Readme: Updated installation instructions for compatibility with Composer 2.2+. #101
• Composer: The minimum PHP_CodeSniffer requirement has been updated to ^3.7.1 (was ^3.3.1). #115, #130
• Composer: The package will now identify itself as a static analysis tool. Thanks @GaryJones! #126
• All non-abstract classes in this package are now final. #121
• All XML documentation now has a schema annotation. #128
• Various housekeeping.

Fixed

The upgrade to PHPCSUtils 1.0.0-alpha4 took care of a number of bugs, which potentially could have affected sniffs in this package.

NormalizedArrays

• NormalizedArrays.Arrays.ArrayBraceSpacing: the sniff now allows for trailing comments after the array opener in multi-line arrays. #118
• NormalizedArrays.Arrays.ArrayBraceSpacing: trailing comments at the end of an array, but before the closer, in multi-line arrays will no longer confuse the sniff. #135
• NormalizedArrays.Arrays.CommaAfterLast: the fixer will now recognize PHP 7.3+ flexible heredoc/nowdocs and in that case, will add the comma on the same line as the heredoc/nowdoc closer. #144

Universal

• Universal.Arrays.DisallowShortArraySyntax: nested short arrays in short lists will now be detected and fixed correctly. #153
• Universal.ControlStructures.DisallowAlternativeSyntax: the sniff will no longer bow out indiscriminately when the allowWithInlineHTML property is set to true. #90, #161
• Universal.ControlStructures.DisallowAlternativeSyntax: when alternative control structure syntax is allowed in combination with inline HTML (allowWithInlineHTML property set to true), inline HTML in functions declared within the control structure body will no longer be taken into account for determining whether or not the control structure contains inline HTML. #160
• Universal.Lists.DisallowShortListSyntax: the sniff will work around a tokenizer bug in PHPCS 3.7.1, which previously could lead to false negatives. #151.
• Universal.Lists.DisallowShortListSyntax: nested short lists in short arrays will now be detected and fixed correctly. #152
• Universal.Operators.DisallowStandalonePostIncrementDecrement: the sniff will now correctly recognize stand-alone statements which end on a PHP close tag. #176

1.0.0-alpha3 - 2020-06-29

Added

Universal

• 🔧 📚 New Universal.Arrays.DisallowShortArraySyntax sniff to disallow short array syntax. #40 In contrast to the PHPCS native Generic.Arrays.DisallowShortArraySyntax sniff, this sniff will ignore short list syntax and not cause parse errors when the fixer is used.
• 🔧 📊 📚 New Universal.Constants.UppercaseMagicConstants sniff to enforce that PHP native magic constants are in uppercase. #64
• 📊 📚 New Universal.Namespaces.DisallowDeclarationWithoutName sniff to disallow namespace declarations without a namespace name. #50
• 📊 📚 New Universal.Operators.DisallowLogicalAndOr sniff to enforce the use of the boolean && and || operators instead of the logical and/or operators. #52 Note: as the operator precedence of the logical operators is significantly lower than the operator precedence of boolean operators, this sniff does not contain an auto-fixer.
• 📊 📚 New Universal.Operators.DisallowShortTernary sniff to disallow the use of short ternaries ?:. #42 While short ternaries are useful when used correctly, the principle of them is often misunderstood and they are more often than not used incorrectly, leading to hard to debug issues and/or PHP warnings/notices.
• 🔧 📊 📚 New Universal.Operators.DisallowStandalonePostIncrementDecrement sniff disallow the use of post-in/decrements in stand-alone statements and discourage the use of multiple increment/decrement operators in a stand-alone statement. #65
• 🔧 📊 📚 New Universal.Operators.StrictComparisons sniff to enforce the use of strict comparisons. #48 Warning: the auto-fixer for this sniff may cause bugs in applications and should be used with care! This is considered a risky fixer.
• 🔧 📊 📚 New Universal.OOStructures.AlphabeticExtendsImplements sniff to verify that the names used in a class "implements" statement or an interface "extends" statement are listed in alphabetic order. #55
  • This sniff contains a public orderby property to determine the sort order to use for the statement. If all names used are unqualified, the sort order won't make a difference. However, if one or more of the names are partially or fully qualified, the chosen sort order will determine how the sorting between unqualified, partially and fully qualified names is handled. The sniff supports two sort order options:
    • 'name' : sort by the interface name only (default);
    • 'full' : sort by the full name as used in the statement (without leading backslash). In both cases, the sorting will be done using natural sort, case-insensitive.
  • The sniff has modular error codes to allow for selective inclusion/exclusion:
    • ImplementsWrongOrder - for "class implements" statements.
    • ImplementsWrongOrderWithComments - for "class implements" statements interlaced with comments. These will not be auto-fixed.
    • ExtendsWrongOrder - for "interface extends" statements.
    • ExtendsWrongOrderWithComments - for "interface extends" statements interlaced with comments. These will not be auto-fixed.
  • When fixing, the existing spacing between the names in an implements/extends statement will not be maintained. The fixer will separate each name with a comma and one space. If alternative formatting is desired, a sniff which will check and fix the formatting should be added to the ruleset.
• 🔧 📊 📚 New Universal.UseStatements.LowercaseFunctionConst sniff to enforce that function and const keywords when used in an import use statement are always lowercase. #58
• 🔧 📊 📚 New Universal.UseStatements.NoLeadingBackslash sniff to verify that a name being imported in an import use statement does not start with a leading backslash. #46 Names in import use statements should always be fully qualified, so a leading backslash is not needed and it is strongly recommended not to use one. This sniff handles all types of import use statements supported by PHP, in contrast to other sniffs for the same in, for instance, the PSR12 or the Slevomat standard, which are incomplete.
• 🔧 📚 New Universal.WhiteSpace.DisallowInlineTabs sniff to enforce using spaces for mid-line alignment. #43

Changed

Other

• The master branch has been renamed to stable.
• Composer: The version requirements for the Composer PHPCS plugin have been widened to allow for version 0.7.0 which supports Composer 2.0.0. #62
• Various housekeeping.

1.0.0-alpha2 - 2020-02-18

Added

Universal

• 🔧 📊 📚 New Universal.ControlStructures.DisallowAlternativeSyntax sniff to disallow using the alternative syntax for control structures. #23
  • This sniff contains a allowWithInlineHTML property to allow alternative syntax when inline HTML is used within the control structure. In all other cases, the use of the alternative syntax will still be disallowed.
  • The sniff has modular error codes to allow for making exceptions based on specific control structures and/or specific control structures in combination with inline HTML.
• 📊 Universal.UseStatements.DisallowUseClass/Function/Const: new, additional metrics about the import source will be shown in the info report. #25

Other

• Readme: installation instructions and sniff list. #26

Changed

Universal

• Universal.Arrays.DuplicateArrayKey: wording of the error message. #18
• Universal.UseStatements.DisallowUseClass/Function/Const: the error codes have been made more modular. #25 Each of these sniffs now has four additional error codes:
  • FoundSameNamespace, FoundSameNamespaceWithAlias for use statements importing from the same namespace;
  • FoundGlobalNamespace, FoundGlobalNamespaceWithAlias for use statements importing from the global namespace, like import statements for PHP native classes, functions and constants.
  In all other circumstances, the existing error codes FoundWithAlias and FoundWithoutAlias will continue to be used.

Other

• Improved formatting of the CLI documentation which can be viewed using --generator=text. #17
• Various housekeeping.

Fixed

Universal

• Universal.Arrays.DuplicateArrayKey: improved handling of parse errors. #34
• Universal.ControlStructures.IfElseDeclaration: the fixer will now respect tab indentation. #19
• Universal.UseStatements.DisallowUseClass/Function/Const: the determination of whether a import is aliased in now done in a case-insensitive manner. #25
• Universal.UseStatements.DisallowUseClass/Function/Const: an import from the global namespace would previously always be seen as non-aliased, even when it was aliased. #25
• Universal.UseStatements.DisallowUseClass/Function/Const: improved tolerance for use import statements with leading backslashes. #25

1.0.0-alpha1 - 2020-01-23

Initial alpha release containing:

• A NormalizedArrays standard which will contain a full set of sniffs to check the formatting of array declarations.
• A Universal standard which will contain a collection of universal sniffs. DO NOT INCLUDE THIS AS A STANDARD. Universal, like the upstream PHPCS Generic standard, contains sniffs which contradict each other. Include individual sniffs from this standard in a custom project/company ruleset to use them.

This initial alpha release contains the following sniffs:

NormalizedArrays

• 🔧 📊 📚 NormalizedArrays.Arrays.ArrayBraceSpacing: enforce consistent spacing for the open/close braces of array declarations. The sniff allows for having different settings for:
  • Space between the array keyword and the open parenthesis for long arrays via the keywordSpacing property. Accepted values: (int) number of spaces or false to turn this check off. Defaults to 0 spaces.
  • Spaces on the inside of the braces for empty arrays via the spacesWhenEmpty property. Accepted values: (string) newline, (int) number of spaces or false to turn this check off. Defaults to 0 spaces.
  • Spaces on the inside of the braces for single-line arrays via the spacesSingleLine property; Accepted values: (int) number of spaces or false to turn this check off. Defaults to 0 spaces.
  • Spaces on the inside of the braces for multi-line arrays via the spacesMultiLine property. Accepted values: (string) newline, (int) number of spaces or false to turn this check off. Defaults to newline. Note: if any of the above properties are set to newline, it is recommended to also include an array indentation sniff. This sniff will not handle the indentation.
• 🔧 📊 📚 NormalizedArrays.Arrays.CommaAfterLast: enforce/forbid a comma after the last item in an array declaration. By default, this sniff will:
  • forbid a comma after the last array item for single-line arrays.
  • enforce a comma after the last array item for multi-line arrays.
  This can be changed for each type or array individually by setting the singleLine or multiLine properties in a custom ruleset. The valid values are: enforce, forbid or skip to not check the comma after the last array item for a particular type of array.

Universal

• 📚 Universal.Arrays.DuplicateArrayKey: detects duplicate array keys in array declarations.
• 📚 Universal.Arrays.MixedArrayKeyTypes: best practice sniff: don't use a mix of integer and numeric keys for array items.
• 📚 Universal.Arrays.MixedKeyedUnkeyedArray: best practice sniff: don't use a mix of keyed and unkeyed array items.
• 🔧 📊 📚 Universal.ControlStructures.IfElseDeclaration: verify that else(if) statements with braces are on a new line.
• 🔧 📊 📚 Universal.Lists.DisallowLongListSyntax: disallow the use of long lists.
• 🔧 📊 📚 Universal.Lists.DisallowShortListSyntax: disallow the use of short lists.
• 📊 📚 Universal.Namespaces.DisallowCurlyBraceSyntax: disallow the use of the alternative namespace declaration syntax using curly braces.
• 📊 📚 Universal.Namespaces.EnforceCurlyBraceSyntax: enforce the use of the alternative namespace syntax using curly braces.
• 📚 Universal.Namespaces.OneDeclarationPerFile: disallow the use of multiple namespaces within a file.
• 📊 📚 Universal.UseStatements.DisallowUseClass: forbid using import use statements for classes/traits/interfaces. Individual sub-types can be allowed by excluding specific error codes.
• 📊 📚 Universal.UseStatements.DisallowUseConst: forbid using import use statements for constants. Individual sub-types can be allowed by excluding specific error codes.
• 📊 📚 Universal.UseStatements.DisallowUseFunction: forbid using import use statements for functions. Individual sub-types can be allowed by excluding specific error codes.