Merge branch 'master' into 4.x

jrfnl · jrfnl · commit 1aca784a2339 · 2025-09-11T07:46:37.000+02:00
diff --git a/src/Files/File.php b/src/Files/File.php
@@ -2438,8 +2438,8 @@ public function findNext(
     /**
      * Returns the position of the first non-whitespace token in a statement.
      *
-     * @param int              $start  The position to start searching from in the token stack.
-     * @param int|string|array $ignore Token types that should not be considered stop points.
+     * @param int                   $start  The position to start searching from in the token stack.
+     * @param int|string|array|null $ignore Token types that should not be considered stop points.
      *
      * @return int
      */
@@ -2629,8 +2629,8 @@ public function findStartOfStatement($start, $ignore=null)
     /**
      * Returns the position of the last non-whitespace token in a statement.
      *
-     * @param int              $start  The position to start searching from in the token stack.
-     * @param int|string|array $ignore Token types that should not be considered stop points.
+     * @param int                   $start  The position to start searching from in the token stack.
+     * @param int|string|array|null $ignore Token types that should not be considered stop points.
      *
      * @return int
      */
@@ -2751,7 +2751,7 @@ public function findEndOfStatement($start, $ignore=null)
      *                                  token stack.
      * @param bool             $exclude If true, find the token that is NOT of
      *                                  the types specified in $types.
-     * @param string           $value   The value that the token must be equal to.
+     * @param string|null      $value   The value that the token must be equal to.
      *                                  If value is omitted, tokens with any value will
      *                                  be returned.
      *
diff --git a/src/Files/FileList.php b/src/Files/FileList.php
@@ -112,8 +112,8 @@ public function __construct(Config $config, Ruleset $ruleset)
      * If a file object has already been created, it can be passed here.
      * If it is left NULL, it will be created when accessed.
      *
-     * @param string                      $path The path to the file being added.
-     * @param \PHP_CodeSniffer\Files\File $file The file being added.
+     * @param string                           $path The path to the file being added.
+     * @param \PHP_CodeSniffer\Files\File|null $file The file being added.
      *
      * @return void
      */
diff --git a/src/Fixer.php b/src/Fixer.php
@@ -226,10 +226,10 @@ public function fixFile()
     /**
      * Generates a text diff of the original file and the new content.
      *
-     * @param string  $filePath Optional file path to diff the file against.
-     *                          If not specified, the original version of the
-     *                          file will be used.
-     * @param boolean $colors   Print coloured output or not.
+     * @param string|null $filePath Optional file path to diff the file against.
+     *                              If not specified, the original version of the
+     *                              file will be used.
+     * @param boolean     $colors   Print coloured output or not.
      *
      * @return string
      *
@@ -682,10 +682,10 @@ public function revertToken($stackPtr)
     /**
      * Replace the content of a token with a part of its current content.
      *
-     * @param int $stackPtr The position of the token in the token stack.
-     * @param int $start    The first character to keep.
-     * @param int $length   The number of characters to keep. If NULL, the content of
-     *                      the token from $start to the end of the content is kept.
+     * @param int      $stackPtr The position of the token in the token stack.
+     * @param int      $start    The first character to keep.
+     * @param int|null $length   The number of characters to keep. If NULL, the content of
+     *                           the token from $start to the end of the content is kept.
      *
      * @return bool If the change was accepted.
      */
diff --git a/src/Ruleset.php b/src/Ruleset.php
@@ -1732,8 +1732,8 @@ private function getRealPropertyValue($value)
      * Optionally takes a listener to get ignore patterns specified
      * for that sniff only.
      *
-     * @param string $listener The listener to get patterns for. If NULL, all
-     *                         patterns are returned.
+     * @param string|null $listener The listener to get patterns for. If NULL, all
+     *                              patterns are returned.
      *
      * @return array
      */
@@ -1758,8 +1758,8 @@ public function getIgnorePatterns($listener=null)
      * Optionally takes a listener to get include patterns specified
      * for that sniff only.
      *
-     * @param string $listener The listener to get patterns for. If NULL, all
-     *                         patterns are returned.
+     * @param string|null $listener The listener to get patterns for. If NULL, all
+     *                              patterns are returned.
      *
      * @return array
      */
diff --git a/src/Standards/Generic/Sniffs/Formatting/MultipleStatementAlignmentSniff.php b/src/Standards/Generic/Sniffs/Formatting/MultipleStatementAlignmentSniff.php
@@ -75,7 +75,7 @@ public function process(File $phpcsFile, $stackPtr)
      * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
      * @param int                         $stackPtr  The position of the current token
      *                                               in the stack passed in $tokens.
-     * @param int                         $end       The token where checking should end.
+     * @param int|null                    $end       The token where checking should end.
      *                                               If NULL, the entire file will be checked.
      *
      * @return int
diff --git a/src/Standards/Generic/Sniffs/PHP/DeprecatedFunctionsSniff.php b/src/Standards/Generic/Sniffs/PHP/DeprecatedFunctionsSniff.php
@@ -53,7 +53,7 @@ public function __construct()
      * @param int                         $stackPtr     The position of the forbidden function
      *                                                  in the token array.
      * @param string                      $functionName The name of the forbidden function.
-     * @param string                      $pattern      The pattern used for the match.
+     * @param string|null                 $pattern      The pattern used for the match.
      *
      * @return void
      */
diff --git a/src/Standards/Generic/Sniffs/PHP/ForbiddenFunctionsSniff.php b/src/Standards/Generic/Sniffs/PHP/ForbiddenFunctionsSniff.php
@@ -206,7 +206,7 @@ public function process(File $phpcsFile, $stackPtr)
      * @param int                         $stackPtr     The position of the forbidden function
      *                                                  in the token array.
      * @param string                      $functionName The name of the forbidden function.
-     * @param string                      $pattern      The pattern used for the match.
+     * @param string|null                 $pattern      The pattern used for the match.
      *
      * @return void
      */
diff --git a/src/Tokenizers/Tokenizer.php b/src/Tokenizers/Tokenizer.php
@@ -493,10 +493,10 @@ private function createPositionMap()
      * is placed into an orig_content index and the new token length is also
      * set in the length index.
      *
-     * @param array  $token    The token to replace tabs inside.
-     * @param string $prefix   The character to use to represent the start of a tab.
-     * @param string $padding  The character to use to represent the end of a tab.
-     * @param int    $tabWidth The number of spaces each tab represents.
+     * @param array    $token    The token to replace tabs inside.
+     * @param string   $prefix   The character to use to represent the start of a tab.
+     * @param string   $padding  The character to use to represent the end of a tab.
+     * @param int|null $tabWidth The number of spaces each tab represents.
      *
      * @return void
      */
diff --git a/src/Util/Cache.php b/src/Util/Cache.php
@@ -302,8 +302,8 @@ public static function save()
     /**
      * Retrieves a single entry from the cache.
      *
-     * @param string $key The key of the data to get. If NULL,
-     *                    everything in the cache is returned.
+     * @param string|null $key The key of the data to get. If NULL,
+     *                         everything in the cache is returned.
      *
      * @return mixed
      */
@@ -325,9 +325,9 @@ public static function get($key=null)
     /**
      * Retrieves a single entry from the cache.
      *
-     * @param string $key   The key of the data to set. If NULL,
-     *                      sets the entire cache.
-     * @param mixed  $value The value to set.
+     * @param string|null $key   The key of the data to set. If NULL,
+     *                           sets the entire cache.
+     * @param mixed       $value The value to set.
      *
      * @return void
      */
diff --git a/src/Util/Tokens.php b/src/Util/Tokens.php
@@ -960,8 +960,8 @@ public static function tokenName($token)
      * @param array<int|string> $tokens The token types to get the highest weighted
      *                                  type for.
      *
-     * @return int The highest weighted token.
-     *             On equal "weight", returns the first token of that particular weight.
+     * @return int|string The highest weighted token.
+     *                    On equal "weight", returns the first token of that particular weight.
      */
     public static function getHighestWeightedToken(array $tokens)
     {

Original file line number	Diff line number	Diff line change
`@@ -2438,8 +2438,8 @@ public function findNext(`
`2438`	`2438`	`/**`
`2439`	`2439`	`* Returns the position of the first non-whitespace token in a statement.`
`2440`	`2440`	`*`
`2441`		`- * @param int $start The position to start searching from in the token stack.`
`2442`		`- * @param int\|string\|array $ignore Token types that should not be considered stop points.`
	`2441`	`+ * @param int $start The position to start searching from in the token stack.`
	`2442`	`+ * @param int\|string\|array\|null $ignore Token types that should not be considered stop points.`
`2443`	`2443`	`*`
`2444`	`2444`	`* @return int`
`2445`	`2445`	`*/`
`@@ -2629,8 +2629,8 @@ public function findStartOfStatement($start, $ignore=null)`
`2629`	`2629`	`/**`
`2630`	`2630`	`* Returns the position of the last non-whitespace token in a statement.`
`2631`	`2631`	`*`
`2632`		`- * @param int $start The position to start searching from in the token stack.`
`2633`		`- * @param int\|string\|array $ignore Token types that should not be considered stop points.`
	`2632`	`+ * @param int $start The position to start searching from in the token stack.`
	`2633`	`+ * @param int\|string\|array\|null $ignore Token types that should not be considered stop points.`
`2634`	`2634`	`*`
`2635`	`2635`	`* @return int`
`2636`	`2636`	`*/`
`@@ -2751,7 +2751,7 @@ public function findEndOfStatement($start, $ignore=null)`
`2751`	`2751`	`* token stack.`
`2752`	`2752`	`* @param bool $exclude If true, find the token that is NOT of`
`2753`	`2753`	`* the types specified in $types.`
`2754`		`- * @param string $value The value that the token must be equal to.`
	`2754`	`+ * @param string\|null $value The value that the token must be equal to.`
`2755`	`2755`	`* If value is omitted, tokens with any value will`
`2756`	`2756`	`* be returned.`
`2757`	`2757`	`*`
Original file line number	Diff line number	Diff line change
`@@ -112,8 +112,8 @@ public function __construct(Config $config, Ruleset $ruleset)`
`112`	`112`	`* If a file object has already been created, it can be passed here.`
`113`	`113`	`* If it is left NULL, it will be created when accessed.`
`114`	`114`	`*`
`115`		`- * @param string $path The path to the file being added.`
`116`		`- * @param \PHP_CodeSniffer\Files\File $file The file being added.`
	`115`	`+ * @param string $path The path to the file being added.`
	`116`	`+ * @param \PHP_CodeSniffer\Files\File\|null $file The file being added.`
`117`	`117`	`*`
`118`	`118`	`* @return void`
`119`	`119`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -226,10 +226,10 @@ public function fixFile()`
`226`	`226`	`/**`
`227`	`227`	`* Generates a text diff of the original file and the new content.`
`228`	`228`	`*`
`229`		`- * @param string $filePath Optional file path to diff the file against.`
`230`		`- * If not specified, the original version of the`
`231`		`- * file will be used.`
`232`		`- * @param boolean $colors Print coloured output or not.`
	`229`	`+ * @param string\|null $filePath Optional file path to diff the file against.`
	`230`	`+ * If not specified, the original version of the`
	`231`	`+ * file will be used.`
	`232`	`+ * @param boolean $colors Print coloured output or not.`
`233`	`233`	`*`
`234`	`234`	`* @return string`
`235`	`235`	`*`
`@@ -682,10 +682,10 @@ public function revertToken($stackPtr)`
`682`	`682`	`/**`
`683`	`683`	`* Replace the content of a token with a part of its current content.`
`684`	`684`	`*`
`685`		`- * @param int $stackPtr The position of the token in the token stack.`
`686`		`- * @param int $start The first character to keep.`
`687`		`- * @param int $length The number of characters to keep. If NULL, the content of`
`688`		`- * the token from $start to the end of the content is kept.`
	`685`	`+ * @param int $stackPtr The position of the token in the token stack.`
	`686`	`+ * @param int $start The first character to keep.`
	`687`	`+ * @param int\|null $length The number of characters to keep. If NULL, the content of`
	`688`	`+ * the token from $start to the end of the content is kept.`
`689`	`689`	`*`
`690`	`690`	`* @return bool If the change was accepted.`
`691`	`691`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -1732,8 +1732,8 @@ private function getRealPropertyValue($value)`
`1732`	`1732`	`* Optionally takes a listener to get ignore patterns specified`
`1733`	`1733`	`* for that sniff only.`
`1734`	`1734`	`*`
`1735`		`- * @param string $listener The listener to get patterns for. If NULL, all`
`1736`		`- * patterns are returned.`
	`1735`	`+ * @param string\|null $listener The listener to get patterns for. If NULL, all`
	`1736`	`+ * patterns are returned.`
`1737`	`1737`	`*`
`1738`	`1738`	`* @return array`
`1739`	`1739`	`*/`
`@@ -1758,8 +1758,8 @@ public function getIgnorePatterns($listener=null)`
`1758`	`1758`	`* Optionally takes a listener to get include patterns specified`
`1759`	`1759`	`* for that sniff only.`
`1760`	`1760`	`*`
`1761`		`- * @param string $listener The listener to get patterns for. If NULL, all`
`1762`		`- * patterns are returned.`
	`1761`	`+ * @param string\|null $listener The listener to get patterns for. If NULL, all`
	`1762`	`+ * patterns are returned.`
`1763`	`1763`	`*`
`1764`	`1764`	`* @return array`
`1765`	`1765`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -75,7 +75,7 @@ public function process(File $phpcsFile, $stackPtr)`
`75`	`75`	`* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.`
`76`	`76`	`* @param int $stackPtr The position of the current token`
`77`	`77`	`* in the stack passed in $tokens.`
`78`		`- * @param int $end The token where checking should end.`
	`78`	`+ * @param int\|null $end The token where checking should end.`
`79`	`79`	`* If NULL, the entire file will be checked.`
`80`	`80`	`*`
`81`	`81`	`* @return int`
Original file line number	Diff line number	Diff line change
`@@ -53,7 +53,7 @@ public function __construct()`
`53`	`53`	`* @param int $stackPtr The position of the forbidden function`
`54`	`54`	`* in the token array.`
`55`	`55`	`* @param string $functionName The name of the forbidden function.`
`56`		`- * @param string $pattern The pattern used for the match.`
	`56`	`+ * @param string\|null $pattern The pattern used for the match.`
`57`	`57`	`*`
`58`	`58`	`* @return void`
`59`	`59`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -206,7 +206,7 @@ public function process(File $phpcsFile, $stackPtr)`
`206`	`206`	`* @param int $stackPtr The position of the forbidden function`
`207`	`207`	`* in the token array.`
`208`	`208`	`* @param string $functionName The name of the forbidden function.`
`209`		`- * @param string $pattern The pattern used for the match.`
	`209`	`+ * @param string\|null $pattern The pattern used for the match.`
`210`	`210`	`*`
`211`	`211`	`* @return void`
`212`	`212`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -302,8 +302,8 @@ public static function save()`
`302`	`302`	`/**`
`303`	`303`	`* Retrieves a single entry from the cache.`
`304`	`304`	`*`
`305`		`- * @param string $key The key of the data to get. If NULL,`
`306`		`- * everything in the cache is returned.`
	`305`	`+ * @param string\|null $key The key of the data to get. If NULL,`
	`306`	`+ * everything in the cache is returned.`
`307`	`307`	`*`
`308`	`308`	`* @return mixed`
`309`	`309`	`*/`
`@@ -325,9 +325,9 @@ public static function get($key=null)`
`325`	`325`	`/**`
`326`	`326`	`* Retrieves a single entry from the cache.`
`327`	`327`	`*`
`328`		`- * @param string $key The key of the data to set. If NULL,`
`329`		`- * sets the entire cache.`
`330`		`- * @param mixed $value The value to set.`
	`328`	`+ * @param string\|null $key The key of the data to set. If NULL,`
	`329`	`+ * sets the entire cache.`
	`330`	`+ * @param mixed $value The value to set.`
`331`	`331`	`*`
`332`	`332`	`* @return void`
`333`	`333`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -960,8 +960,8 @@ public static function tokenName($token)`
`960`	`960`	`* @param array<int\|string> $tokens The token types to get the highest weighted`
`961`	`961`	`* type for.`
`962`	`962`	`*`
`963`		`- * @return int The highest weighted token.`
`964`		`- * On equal "weight", returns the first token of that particular weight.`
	`963`	`+ * @return int\|string The highest weighted token.`
	`964`	`+ * On equal "weight", returns the first token of that particular weight.`
`965`	`965`	`*/`
`966`	`966`	`public static function getHighestWeightedToken(array $tokens)`
`967`	`967`	`{`