ADD TO: Dev upgrade guide

Author: jrfnl

wiki/Version-4.0-Developer-Upgrade-Guide.md

@@ -51,7 +51,7 @@ There is a separate [[Upgrade Guide for Ruleset Maintainers and End-Users|Versio
 
 It is highly recommended to upgrade external standards and integrations as soon as you are able.
 
-Once PHP_CodeSniffer 4.0 has been released, the PHP_CodeSniffer 3.x branch will no longer receive updates, with the exception of security fixes and runtime compatibility fixes for new PHP versions.
+Once PHP_CodeSniffer 4.0 has been released, the PHP_CodeSniffer 3.x branch will no longer receive updates, with the exception of security fixes and runtime compatibility fixes for new PHP versions.  
 This "limited support" will last a maximum of one year from the date of the PHP_CodeSniffer 4.0.0 release.
 
 > [!IMPORTANT]
@@ -106,7 +106,7 @@ Please carefully read the naming conventions for standards and sniffs as outline
 
 ... either directly or indirectly via an abstract sniff. This is now actively enforced.
 
-PHP_CodeSniffer 3.13.0 will throw a deprecation notice for any sniffs which don't implement the interface.
+PHP_CodeSniffer 3.13.0 will throw a deprecation notice for any sniffs which don't implement the interface.  
 As of PHP_CodeSniffer 4.0.0, PHP_CodeSniffer will error out on such sniffs.
 
 <p align="right"><a href="#table-of-contents">back to top</a></p>
@@ -116,9 +116,9 @@ As of PHP_CodeSniffer 4.0.0, PHP_CodeSniffer will error out on such sniffs.
 
 Support for the JS/CSS tokenizers has been removed. To cause the least amount of friction, this has been executed as follows:
 
-* Sniffs which specify the `$supportedTokenizers` property and don't include `'PHP'` in the array value will no longer run on PHPCS 4.0.
-    The end-user will be shown an error message about this and PHP_CodeSniffer will exit with this error.
-    This error message can be silenced by implementing the `PHP_CodeSniffer\Sniffs\DeprecatedSniff` interface (PHPCS 3.9.0+) to mark the sniff as deprecated.
+* Sniffs which specify the `$supportedTokenizers` property and don't include `'PHP'` in the array value will no longer run on PHPCS 4.0.  
+    The end-user will be shown an error message about this and PHP_CodeSniffer will exit with this error.  
+    This error message can be silenced by implementing the `PHP_CodeSniffer\Sniffs\DeprecatedSniff` interface (PHPCS 3.9.0+) to mark the sniff as deprecated.  
     In that case, the sniff will show a deprecation notice when running on PHPCS 3.x and the sniff will be silently ignored on PHPCS 4.x.
 * Sniffs which specify the `$supportedTokenizers` property and include both `'PHP'` as well as something else, will run against the scanned files, with all files being treated as PHP, as of PHPCS 4.0.0 and will not cause any notices about the sniff to be shown to the end-user.
 
@@ -171,10 +171,10 @@ Additionally, when a name could not be determined, like during live coding, the
 It is recommended to search your codebase for all uses of the `File::getDeclarationName()` method and to review whether the code needs updating.
 
 Typically:
-* Verify that the sniff does not pass anonymous constructs to the method.
+* Verify that the sniff does not pass anonymous constructs to the method.  
     If necessary, either add guard-code to prevent this, or wrap the method call in a `try ... catch`.
-* Verify if the return value of the method is checked correctly.
-    For PHPCS cross-version compatibility, check the return value with `empty($name)`.
+* Verify if the return value of the method is checked correctly.  
+    For PHPCS cross-version compatibility, check the return value with `empty($name)`.  
     If cross-version compatibility is not a concern, replace checks against `null` with a check against an empty string.
     ```diff
     $name = $phpcsFile->getDeclarationName($stackPtr);
@@ -228,7 +228,7 @@ Typically, this may impact projects which call `new Config` consecutive times pr
 
 ##### Upgrading
 
-Typical work-arounds for the old behaviour will use `Reflection` to reset the `Config::$overriddenDefaults` property between instantiations.
+Typical work-arounds for the old behaviour will use `Reflection` to reset the `Config::$overriddenDefaults` property between instantiations.  
 These type of work-arounds can now be removed.
 
 <p align="right"><a href="#table-of-contents">back to top</a></p>
@@ -302,8 +302,8 @@ The following tokens have been removed:
 
 ##### Upgrading
 
-If these tokens are used in PHP-only sniffs, they can be safely removed.
-If these tokens are used in JS/CSS only sniffs, as mentioned in ["Support for JS/CSS has been removed"](#support-for-jscss-has-been-removed): deprecate or remove the sniff.
+If these tokens are used in PHP-only sniffs, they can be safely removed.  
+If these tokens are used in JS/CSS only sniffs, as mentioned in ["Support for JS/CSS has been removed"](#support-for-jscss-has-been-removed): deprecate or remove the sniff.  
 If these tokens are used in mixed sniffs, which also scan PHP files, remove the CSS/JS specific code or, for cross-version compatibility, check for the existance of the tokens before using them.
 
 <p align="right"><a href="#table-of-contents">back to top</a></p>
@@ -317,10 +317,10 @@ These tokens have been added to the `Tokens::$parenthesisOpeners` array and will
 
 ##### Upgrading
 
-* Check if any of your sniffs/code uses the `Tokens::$parenthesisOpeners` array.
-    It is generally discouraged to use that token array as it is mostly intended for internal use by PHPCS itself, but if you do use it, be aware that the above mentioned tokens have been added to the array.
+* Check if any of your sniffs/code uses the `Tokens::$parenthesisOpeners` array.  
+    It is generally discouraged to use that token array as it is mostly intended for internal use by PHPCS itself, but if you do use it, be aware that the above mentioned tokens have been added to the array.  
     You may want to exclude them from your sniff, or in case of `T_USE`, you may need to validate that it is a closure `use` token and not an import/trait `use` token before acting on the token.
-* Search your codebase for `T_USE`, `T_ISSET`, `T_UNSET`, `T_EMPTY`, `T_EVAL`, `T_EXIT`.
+* Search your codebase for `T_USE`, `T_ISSET`, `T_UNSET`, `T_EMPTY`, `T_EVAL`, `T_EXIT`.  
     Anywhere the parentheses for those tokens are "manually" determined, either for use in the sniff or to skip over them, you can now use the `parenthesis_owner`, `parenthesis_opener` and `parenthesis_closer` keys instead.
 
 <p align="right"><a href="#table-of-contents">back to top</a></p>
@@ -330,7 +330,7 @@ These tokens have been added to the `Tokens::$parenthesisOpeners` array and will
 
 The tokenization of identifier names has changed.
 
-This change was made in PHP itself in 8.0 and was "undone" in PHP_CodeSniffer for the PHPCS 3.x releases.
+This change was made in PHP itself in 8.0 and was "undone" in PHP_CodeSniffer for the PHPCS 3.x releases.  
 As of PHPCS 4.0, identifier names will tokenize following the PHP 8.0+ tokenization.
 
 The following type of code is affected:
@@ -373,7 +373,7 @@ This re-tokenization has now been removed.
 
 #### T_OPEN_TAG
 
-Long open tags will no longer include any whitespace. Previously the `T_OPEN_TAG` when used for long open tags could potentially include a single space or a new line character.
+Long open tags will no longer include any whitespace. Previously the `T_OPEN_TAG` when used for long open tags could potentially include a single space or a new line character.  
 Any potential whitespace previously included will now be tokenized as `T_WHITESPACE` following the normal whitespace tokenization rules.
 
 > [!NOTE]
@@ -418,10 +418,10 @@ doSomething();
 
 #### Other Tokenizer Changes
 
-* All `T_DOC_COMMENT_*` tokens will now have the `comment_opener` and `comment_closer` indexes set.
+* All `T_DOC_COMMENT_*` tokens will now have the `comment_opener` and `comment_closer` indexes set.  
     This should allow for more flexibility for sniffs examining aspects of docblocks.
 
-* The `Tokens::FUNCTION_NAME_TOKENS` token array, as well as the deprecated `Tokens::$functionNameTokens`, now also contains the `T_ANON_CLASS` token.
+* The `Tokens::FUNCTION_NAME_TOKENS` token array, as well as the deprecated `Tokens::$functionNameTokens`, now also contains the `T_ANON_CLASS` token.  
     If you use this token array in your sniffs, you will need to evaluate whether this is a desired change or will need excluding.
 
 <p align="right"><a href="#table-of-contents">back to top</a></p>
@@ -431,7 +431,7 @@ doSomething();
 
 The `AbstractPatternSniff::__construct()` method no longer takes any arguments. The `$ignoreComments` parameter was deprecated in PHPCS 1.4.0.
 
-Since PHPCS 1.4.0, the  AbstractPatternSniff sets the `ignoreComments` option using a `public` var rather than through the constructor.
+Since PHPCS 1.4.0, the  AbstractPatternSniff sets the `ignoreComments` option using a `public` var rather than through the constructor.  
 This allows the setting to be overwritten in `ruleset.xml` files.
 
 #### Upgrading
@@ -490,11 +490,11 @@ The `protected` `getDeclarationNameWithNamespace()` and `getNamespaceOfScope()`
 
 * The signature of the `DummyFile::setErrorCounts()` method has changed and now expects the following parameters: `$errorCount, $warningCount, $fixableErrorCount, $fixableWarningCount, $fixedErrorCount, $fixedWarningCount`.
 
-* The abstract `PHP_CodeSniffer\Filters\ExactMatch::getBlacklist()` and `PHP_CodeSniffer\Filters\ExactMatch::getWhitelist()` methods have been replaced with abstract `PHP_CodeSniffer\ExactMatch::getDisallowedFiles()` and `PHP_CodeSniffer\ExactMatch::getAllowedFiles()` methods.
-    If you have custom classes which extend the `ExactMatch` class, implement the new `getDisallowedFiles()` and `getAllowedFiles()` methods instead.
+* The abstract `PHP_CodeSniffer\Filters\ExactMatch::getBlacklist()` and `PHP_CodeSniffer\Filters\ExactMatch::getWhitelist()` methods have been replaced with abstract `PHP_CodeSniffer\ExactMatch::getDisallowedFiles()` and `PHP_CodeSniffer\ExactMatch::getAllowedFiles()` methods.  
+    If you have custom classes which extend the `ExactMatch` class, implement the new `getDisallowedFiles()` and `getAllowedFiles()` methods instead.  
     Note: this is a name change only. The functionality remains the same.
 
-* Various `print*(): void` methods in the Generator classes have been removed in favour of `get*(): string` methods.
+* Various `print*(): void` methods in the Generator classes have been removed in favour of `get*(): string` methods.  
     If you extend any of the `Generator` classes...:
 
     | Search for                                                        | Replace with                                                             |
@@ -514,16 +514,16 @@ The `protected` `getDeclarationNameWithNamespace()` and `getNamespaceOfScope()`
 
 * The `PHP_CodeSniffer\Reporter::$startTime` property has been removed. This property was unused since PHPCS 3.0.0.
 
-* The `PHP_CodeSniffer\Reporter::$totalFixable` and `Reporter::$totalFixed` properties are deprecated and should no longer be used.
+* The `PHP_CodeSniffer\Reporter::$totalFixable` and `Reporter::$totalFixed` properties are deprecated and should no longer be used.  
     Use respectively `(Reporter::$totalFixableErrors + Reporter::$totalFixableWarnings)` and `(Reporter::$totalFixedErrors + Reporter::$totalFixedWarnings)` instead.
 
-* `PHP_CodeSniffer\Ruleset::setSniffProperty()`: the BC-layer supporting the old array format for the `$settings` parameter for the method has been removed.
-    The `$settings` parameter must be passed as an array with the following two keys: `'scope'` and `'value'`, with `'scope'` being set to either `'sniff'` or `'standard'`, and `'value'` containing the new property value.
+* `PHP_CodeSniffer\Ruleset::setSniffProperty()`: the BC-layer supporting the old array format for the `$settings` parameter for the method has been removed.  
+    The `$settings` parameter must be passed as an array with the following two keys: `'scope'` and `'value'`, with `'scope'` being set to either `'sniff'` or `'standard'`, and `'value'` containing the new property value.  
     Also see [squizlabs/PHP_CodeSniffer#3629](https://github.com/squizlabs/PHP_CodeSniffer/pull/3629).
 
-* Various class properties have been replaced with class constants. Where these were in the public API (= the below list), the properties still exist, but are now (soft) deprecated and will be removed in PHP_CodeSniffer 5.0.
-    The visibility of the (deprecated) properties and their class constant replacements is the same.
-    If you previously overloaded one of these properties in a custom sniff extending one of the affected sniffs, you will now need to overload the class constant.
+* Various class properties have been replaced with class constants. Where these were in the public API (= the below list), the properties still exist, but are now (soft) deprecated and will be removed in PHP_CodeSniffer 5.0.  
+    The visibility of the (deprecated) properties and their class constant replacements is the same.  
+    If you previously overloaded one of these properties in a custom sniff extending one of the affected sniffs, you will now need to overload the class constant.  
     To obtain cross-version compatibility with PHPCS 3.x as well as 4.x, you may need to overload both the property as well as the constant.
 
     | Search for                          | Replace with                         | Notes    |
@@ -575,8 +575,8 @@ Typically, these type of work-around can be found by searching for calls to the
 External standards which use the PHP_CodeSniffer native test framework as the basis for the sniff tests need to be aware of the following changes.
 If an external standard uses its own test framework, this section can be skipped.
 
-* The test setup now supports PHPUnit 8, 9, 10 and 11, which is in line with the new minimum PHP version of 7.2.
-    Please read the changelogs for PHPUnit itself for information about the changes.
+* The test setup now supports PHPUnit 8, 9, 10 and 11, which is in line with the new minimum PHP version of 7.2.  
+    Please read the changelogs for PHPUnit itself for information about the changes.  
     Most notable changes which will likely impact your tests:
     * The test suite may need a separate PHPUnit config file for PHPUnit < 10 and PHPUnit 10+.
 * The custom `TestSuite` setup has been removed from the framework as it is no longer needed since PEAR support was dropped and was incompatible with PHPUnit 10.
@@ -587,17 +587,17 @@ If an external standard uses its own test framework, this section can be skipped
     | PHP_CodeSniffer\Tests\Core\AbstractMethodUnitTest     | PHP_CodeSniffer\Tests\Core\AbstractMethodTestCase     |
     | PHP_CodeSniffer\Tests\Standards\AbstractSniffUnitTest | PHP_CodeSniffer\Tests\Standards\AbstractSniffTestCase |
 
-* Fixture methods no longer use the `@before|after[Class]` annotations, but use the PHPUnit `setUp|tearDown[BeforeClass|AfterClass]()` methods again.
+* Fixture methods no longer use the `@before|after[Class]` annotations, but use the PHPUnit `setUp|tearDown[BeforeClass|AfterClass]()` methods again.  
     These methods now have `void` return type declarations.
 * The global `printPHPCodeSnifferTestOutput()` function, which printed a "# sniff test files generated # unique error codes; # were fixable (#%)" summary after the tests is no longer available.
 * The following properties which were previously available in the `AbstractSniffUnitTest` class have been removed:
     * `protected $backupGlobals`
     * `public $standardsDir`
     * `public $testsDir`
-    The first is (very) old-school PHPUnit and should not be used anyway.
+    The first is (very) old-school PHPUnit and should not be used anyway.  
     The last two were never intended to be overwritten by concrete test classes, so shouldn't have been public properties.
 * The following property which was previously available in the `AbstractMethodUnitTest` class has been removed:
-    * `protected static $fileExtension`
+    * `protected static $fileExtension`  
        This property is redundant now support for JS/CSS files has been dropped.
 * The test framework no longer uses global variables. I.e. the following are no longer available:
     * `$GLOBALS['PHP_CODESNIFFER_STANDARD_DIRS']`
@@ -616,10 +616,10 @@ This is not really any different from before, just even more important now.
 #### Upgrading
 
 In practice this means the following for most test suites for external standards which extend the PHP_CodeSniffer native test suite:
-1. In `composer.json`: update the PHPUnit version requirements.
+1. In `composer.json`: update the PHPUnit version requirements.  
     The PHP_CodeSniffer native test framework supports PHPUnit `^8.0 || ^9.3.4 || ^10.5.32 || ^11.3.3` as of PHP_CodeSniffer 4.0.0.
 2. In the `phpunit.xml[.dist]` file: ensure that this file contains a `<testsuites>` element which points to your test directory/directories.
-3. In the test bootstrap file: register your own standard and any other external standards your standard needs with the autoloader.
+3. In the test bootstrap file: register your own standard and any other external standards your standard needs with the autoloader.  
     Typically, this can be done using the following code snippet after loading the PHPCS `autoload.php` file:
     ```php
     $installedStandards = Standards::getInstalledStandardDetails();
@@ -638,7 +638,7 @@ In practice this means the following for most test suites for external standards
     +final class YourSniffNameUnitTest extends AbstractSniffTestCase {
     ```
     External standards which want to support PHP_CodeSniffer 3 and 4 and run their tests on both could consider aliasing the name of the test case class in their test bootstrap file.
-6. Make sure that all `inc` test case files which test fixers are accompanied by a `.inc.fixed` file.
+6. Make sure that all `inc` test case files which test fixers are accompanied by a `.inc.fixed` file.  
     In PHPCS 3.x, the test framework would already warn about any missing `.fixed` files. This has now become an error which will fail a test run.
 7. For running the tests: do not pass the `./vendor/squizlabs/php_codesniffer/tests/AllTests.php` file anymore and the `--filter ExternalStndName` argument should also no longer be needed. Run the tests for your external standard by calling plain `phpunit`.