Changelog for the 3.12.0 release

CHANGELOG.md

@@ -6,12 +6,179 @@ The file documents changes to the PHP_CodeSniffer project.
 
 _Nothing yet._
 
+## [3.12.0] - 2025-03-18
+
+### Added
+- Added support for PHP 8.4 `final` properties to File::getMemberProperties() through a new `is_final` array index in the return value. [#834]
+    - Thanks to [Daniel Scherzer][@DanielEScherzer] for the patch.
+- Generators/HTML: each section title now has a unique anchor link, which can be copied when hovering over a title. [#859]
+    - This should make sharing a link to a specific section of the documentation more straight-forward.
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+- Documentation for the following sniffs:
+    - Squiz.Classes.ClassFileName
+    - Squiz.Classes.ValidClassName
+    - Thanks to [Brian Dunne][@braindawg] for the patches.
+
+### Changed
+- PHPCBF: the messaging when no fixable errors are found will now distinguish between "No violations" (at all) versus "No fixable errors". [#806]
+    - Thanks to [Peter Wilson][@peterwilsoncc] for the patch.
+- The `-h` (Help) option now contains a more extensive list of "config" options which can be set. [#809]
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+- Improved error message when invalid sniff codes are supplied to `--sniffs` or `--exclude` command line arguments. [#344]
+    - Thanks to [Dan Wallis][@fredden] for the patch.
+- Improved error message when an invalid generator name is supplied to the `--generator` command line argument. [#709], [#771]
+    - The generator name will now also always be handled case-insensitively, independently of the OS used.
+    - Thanks to [Rodrigo Primo][@rodrigoprimo] for the patch.
+- The user will be shown an informative error message for sniffs missing one of the required methods. [#873]
+    - Previously this would result in a fatal error.
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+- Ruleset processing will now be allowed to run to its conclusion - barring critical errors - before displaying all ruleset errors in one go. [#857]
+    - Previously an error in a ruleset would cause PHPCS to exit immediately and show only one error at a time.
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+- Generators: XML documentation files which don't contain any actual documentation will now silently be ignored. [#755]
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+- Generators: when the `title` attribute is missing, the documentation generation will now fall back to the sniff name as the title. [#820]
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+- Generators: cleaner output based on the elements of the documentation which are available. [#819], [#821]
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+- Generators/HTML: improved display of code tables by using semantic HTML. [#854]
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+- Squiz.Classes.ClassFileName: recommend changing the file name instead of changing the class name. [#845]
+    - This prevents unactionable recommendations due to the file name not translating to a valid PHP symbol name.
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+- Squiz.Functions.FunctionDeclarationArgumentSpacing: incorrect spacing after a comma followed by a promoted property has an improved error message and will now be flagged with the `SpacingBeforePropertyModifier` or `NoSpaceBeforePropertyModifier` error codes. [#792]
+    - This was previously already flagged, but using either the `SpacingBeforeHint` or `NoSpaceBeforeHint` error code, which was misleading.
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+- Squiz.Functions.FunctionDeclarationArgumentSpacing: the sniff will now also check the spacing after property modifiers for promoted properties in constructor methods. [#792]
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+- Squiz.WhiteSpace.ScopeKeywordSpacing: the sniff will now also check the spacing after the `final` and `abstract` modifier keywords. [#604]
+    - Thanks to [Klaus Purer][@klausi] for the patch.
+- The following sniff(s) have received efficiency improvements:
+    - Squiz.WhiteSpace.ScopeKeywordSpacing
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patches.
+- Incorrectly set inline properties (in test case files) will be silently ignored again. [#884]
+    - This removes the `Internal.PropertyDoesNotExist` error code.
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+- The AbstractMethodUnitTest class will now flag duplicate test case markers in a test case file. [#773]
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+- Various housekeeping, including improvements to the tests and documentation.
+    - Thanks to [Asis Pattisahusiwa][@asispts], [Dan Wallis][@fredden], [Rodrigo Primo][@rodrigoprimo] and [Juliette Reinders Folmer][@jrfnl] for their contributions.
+
+### Deprecated
+All deprecation are slated for removal in PHP_CodeSniffer 4.0.
+
+- Support for sniffs not implementing the PHPCS `Sniff` interface. See [#694].
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+- Support for including sniffs which don't comply with the PHPCS naming conventions (by referencing the sniff file directly). See [#689].
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+- Support for external standards named "Internal". See [#799].
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+- The following Generator methods are now (soft) deprecated. See [#755]:
+    - `PHP_CodeSniffer\Generators\Text::printTitle()` in favour of `PHP_CodeSniffer\Generators\Text::getFormattedTitle()`
+    - `PHP_CodeSniffer\Generators\Text::printTextBlock()` in favour of `PHP_CodeSniffer\Generators\Text::getFormattedTextBlock()`
+    - `PHP_CodeSniffer\Generators\Text::printCodeComparisonBlock()` in favour of `PHP_CodeSniffer\Generators\Text::getFormattedCodeComparisonBlock()`
+    - `PHP_CodeSniffer\Generators\Markdown::printHeader()` in favour of `PHP_CodeSniffer\Generators\Markdown::getFormattedHeader()`
+    - `PHP_CodeSniffer\Generators\Markdown::printFooter()` in favour of `PHP_CodeSniffer\Generators\Markdown::getFormattedFooter()`
+    - `PHP_CodeSniffer\Generators\Markdown::printTextBlock()` in favour of `PHP_CodeSniffer\Generators\Markdown::getFormattedTextBlock()`
+    - `PHP_CodeSniffer\Generators\Markdown::printCodeComparisonBlock()` in favour of `PHP_CodeSniffer\Generators\Markdown::getFormattedCodeComparisonBlock()`
+    - `PHP_CodeSniffer\Generators\HTML::printHeader()` in favour of `PHP_CodeSniffer\Generators\HTML::getFormattedHeader()`
+    - `PHP_CodeSniffer\Generators\HTML::printToc()` in favour of `PHP_CodeSniffer\Generators\HTML::getFormattedToc()`
+    - `PHP_CodeSniffer\Generators\HTML::printFooter()` in favour of `PHP_CodeSniffer\Generators\HTML::getFormattedFooter()`
+    - `PHP_CodeSniffer\Generators\HTML::printTextBlock()` in favour of `PHP_CodeSniffer\Generators\HTML::getFormattedTextBlock()`
+    - `PHP_CodeSniffer\Generators\HTML::printCodeComparisonBlock()` in favour of `PHP_CodeSniffer\Generators\HTML::getFormattedCodeComparisonBlock()`
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+
+### Fixed
+- Fixed bug [#794] : Generators: prevent fatal error when the XML documentation does not comply with the expected format.
+    - It is recommended to validate XML documentation files against the XSD file: <https://phpcsstandards.github.io/PHPCSDevTools/phpcsdocs.xsd>
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+- Fixed bug [#814] : Generic.NamingConventions.ConstructorName: prevent potential fatal errors during live coding.
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+- Fixed bug [#816] : File::getDeclarationName(): prevent incorrect result for unfinished closures during live coding.
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+- Fixed bug [#817] : Squiz.Classes.ValidClassName: ignore comments when determining the name to be validated.
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+- Fixed bug [#825] : Squiz.Classes.ClassDeclaration: false positives when the next thing after a class was a function with an attribute attached.
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+- Fixed bug [#826] : Squiz.WhiteSpace.FunctionSpacing: prevent incorrect some results when attributes are attached to a function.
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+- Fixed bug [#827] : PEAR.Functions.FunctionDeclaration: fixer conflict over an unfinished closure during live coding.
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+- Fixed bug [#828] : Squiz.WhiteSpace.MemberVarSpacing: allow for `readonly` properties.
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+- Fixed bug [#832] : Squiz.WhiteSpace.MemberVarSpacing: prevent potential fixer conflict during live coding.
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+- Fixed bug [#833] : Squiz.PHP.EmbeddedPhp: fixer conflict when a PHP open tag for a multi-line snippet is found on the same line as a single-line embedded PHP snippet.
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+- Fixed bug [#833] : Squiz.PHP.EmbeddedPhp: incorrect indent calculation in certain specific situations.
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+- Fixed bug [#835] : Generic.PHP.DisallowShortOpenTag: don't act on parse errors.
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+- Fixed bug [#838] : Squiz.PHP.EmbeddedPhp: no new line before close tag was incorrectly enforced when a preceding OO construct or function had a trailing comment after the close curly.
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+- Fixed bug [#840] : Squiz.WhiteSpace.MemberVarSpacing: more accurate reporting on blank lines in the property "pre-amble" (i.e. docblock, attributes).
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+- Fixed bug [#845] : Squiz.Classes.ClassFileName: don't throw an incorrect error for an unfinished OO declaration during live coding.
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+- Fixed bug [#865] : Setting an array property to an empty array from an XML ruleset now works correctly.
+    - Previously, the property value would be set to `[0 => '']`.
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+- Fixed bug [#866] : Squiz.WhiteSpace.FunctionOpeningBraceSpace: XML docs were not accessible due to an issue with the file name.
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
+
+### Other
+- A new [wiki page][wiki-about-standards] is available to clarify the difference between a project ruleset and an external standard.
+    - This wiki page also contains detailed information about the naming conventions external standards must comply with.
+- A new [XMLLint validate][xmllint-validate] action runner is available which can be used in CI to validate rulesets for PHP_CodeSniffer against the XSD.
+
+[wiki-about-standards]: https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki/About-Standards-for-PHP_CodeSniffer
+[xmllint-validate]: https://github.com/marketplace/actions/xmllint-validate
+
+[#344]: https://github.com/PHPCSStandards/PHP_CodeSniffer/pull/344
+[#604]: https://github.com/PHPCSStandards/PHP_CodeSniffer/pull/604
+[#689]: https://github.com/PHPCSStandards/PHP_CodeSniffer/issues/689
+[#694]: https://github.com/PHPCSStandards/PHP_CodeSniffer/issues/694
+[#709]: https://github.com/PHPCSStandards/PHP_CodeSniffer/issues/709
+[#755]: https://github.com/PHPCSStandards/PHP_CodeSniffer/pull/755
+[#771]: https://github.com/PHPCSStandards/PHP_CodeSniffer/pull/771
+[#773]: https://github.com/PHPCSStandards/PHP_CodeSniffer/issues/773
+[#792]: https://github.com/PHPCSStandards/PHP_CodeSniffer/pull/792
+[#794]: https://github.com/PHPCSStandards/PHP_CodeSniffer/pull/794
+[#799]: https://github.com/PHPCSStandards/PHP_CodeSniffer/issues/799
+[#806]: https://github.com/PHPCSStandards/PHP_CodeSniffer/issues/806
+[#809]: https://github.com/PHPCSStandards/PHP_CodeSniffer/pull/809
+[#814]: https://github.com/PHPCSStandards/PHP_CodeSniffer/pull/814
+[#816]: https://github.com/PHPCSStandards/PHP_CodeSniffer/pull/816
+[#817]: https://github.com/PHPCSStandards/PHP_CodeSniffer/pull/817
+[#819]: https://github.com/PHPCSStandards/PHP_CodeSniffer/pull/819
+[#820]: https://github.com/PHPCSStandards/PHP_CodeSniffer/pull/820
+[#821]: https://github.com/PHPCSStandards/PHP_CodeSniffer/pull/821
+[#825]: https://github.com/PHPCSStandards/PHP_CodeSniffer/pull/825
+[#826]: https://github.com/PHPCSStandards/PHP_CodeSniffer/pull/826
+[#827]: https://github.com/PHPCSStandards/PHP_CodeSniffer/pull/827
+[#828]: https://github.com/PHPCSStandards/PHP_CodeSniffer/pull/828
+[#832]: https://github.com/PHPCSStandards/PHP_CodeSniffer/pull/832
+[#833]: https://github.com/PHPCSStandards/PHP_CodeSniffer/pull/833
+[#834]: https://github.com/PHPCSStandards/PHP_CodeSniffer/pull/834
+[#835]: https://github.com/PHPCSStandards/PHP_CodeSniffer/pull/835
+[#838]: https://github.com/PHPCSStandards/PHP_CodeSniffer/pull/838
+[#840]: https://github.com/PHPCSStandards/PHP_CodeSniffer/pull/840
+[#845]: https://github.com/PHPCSStandards/PHP_CodeSniffer/pull/845
+[#854]: https://github.com/PHPCSStandards/PHP_CodeSniffer/pull/854
+[#857]: https://github.com/PHPCSStandards/PHP_CodeSniffer/pull/857
+[#859]: https://github.com/PHPCSStandards/PHP_CodeSniffer/pull/859
+[#865]: https://github.com/PHPCSStandards/PHP_CodeSniffer/pull/865
+[#866]: https://github.com/PHPCSStandards/PHP_CodeSniffer/pull/866
+[#873]: https://github.com/PHPCSStandards/PHP_CodeSniffer/pull/873
+[#884]: https://github.com/PHPCSStandards/PHP_CodeSniffer/pull/884
+
 ## [3.11.3] - 2025-01-23
 
 ### Changed
 - Generic.ControlStructures.InlineControlStructure no longer unnecessarily listens for T_SWITCH tokens. [#595]
     - Thanks to [Rodrigo Primo][@rodrigoprimo] for the patch.
 - Squiz.Functions.FunctionDeclarationArgumentSpacing: improvements to error message for `SpaceBeforeComma` error. [#783]
+    - Thanks to [Juliette Reinders Folmer][@jrfnl] for the patch.
 - The following sniff(s) have received efficiency improvements:
     - Squiz.Functions.FunctionDeclarationArgumentSpacing
     - Thanks to [Dan Wallis][@fredden] and [Juliette Reinders Folmer][@jrfnl] for the patches.
@@ -7245,6 +7412,7 @@ Additionally, thanks to [Alexander Turek][@derrabus] for consulting on the repo
 -->
 
 [Unreleased]: https://github.com/PHPCSStandards/PHP_CodeSniffer/compare/master...HEAD
+[3.12.0]:     https://github.com/PHPCSStandards/PHP_CodeSniffer/compare/3.11.3...3.12.0
 [3.11.3]:     https://github.com/PHPCSStandards/PHP_CodeSniffer/compare/3.11.2...3.11.3
 [3.11.2]:     https://github.com/PHPCSStandards/PHP_CodeSniffer/compare/3.11.1...3.11.2
 [3.11.1]:     https://github.com/PHPCSStandards/PHP_CodeSniffer/compare/3.11.0...3.11.1
@@ -7369,6 +7537,7 @@ Additionally, thanks to [Alexander Turek][@derrabus] for consulting on the repo
 [@annechko]:            https://github.com/annechko
 [@anomiex]:             https://github.com/anomiex
 [@arnested]:            https://github.com/arnested
+[@asispts]:             https://github.com/asispts
 [@asnyder]:             https://github.com/asnyder
 [@Astinus-Eberhard]:    https://github.com/Astinus-Eberhard
 [@axlon]:               https://github.com/axlon
@@ -7385,6 +7554,7 @@ Additionally, thanks to [Alexander Turek][@derrabus] for consulting on the repo
 [@blue32a]:             https://github.com/blue32a
 [@bondas83]:            https://github.com/bondas83
 [@boonkerz]:            https://github.com/boonkerz
+[@braindawg]:           https://github.com/braindawg
 [@BRMatt]:              https://github.com/BRMatt
 [@CandySunPlus]:        https://github.com/CandySunPlus
 [@ceeram]:              https://github.com/ceeram
@@ -7396,6 +7566,7 @@ Additionally, thanks to [Alexander Turek][@derrabus] for consulting on the repo
 [@cweiske]:             https://github.com/cweiske
 [@Daimona]:             https://github.com/Daimona
 [@danez]:               https://github.com/danez
+[@DanielEScherzer]:     https://github.com/DanielEScherzer
 [@DannyvdSluijs]:       https://github.com/DannyvdSluijs
 [@das-peter]:           https://github.com/das-peter
 [@datengraben]:         https://github.com/datengraben
@@ -7508,6 +7679,7 @@ Additionally, thanks to [Alexander Turek][@derrabus] for consulting on the repo
 [@ondrejmirtes]:        https://github.com/ondrejmirtes
 [@orx0r]:               https://github.com/orx0r
 [@ostrolucky]:          https://github.com/ostrolucky
+[@peterwilsoncc]:       https://github.com/peterwilsoncc
 [@pfrenssen]:           https://github.com/pfrenssen
 [@phil-davis]:          https://github.com/phil-davis
 [@photodude]:           https://github.com/photodude