From d0d52cdd56c9e60d599d9c0c952639bf33db403d Mon Sep 17 00:00:00 2001 From: jrfnl Date: Thu, 22 Aug 2024 12:03:09 +0200 Subject: [PATCH] CS/QA: rename various parameters While reserved keywords can be used as parameter names without issue, it makes for very confusing code when the PHP 8.0 "named arguments in function calls" feature would be used. With this in mind, any such a parameters are now renamed. Loosely related to 392 --- autoload.php | 32 +++++----- src/Config.php | 8 +-- .../Sniffs/PHP/DeprecatedFunctionsSniff.php | 14 ++--- .../Sniffs/PHP/ForbiddenFunctionsSniff.php | 16 ++--- src/Tokenizers/Comment.php | 54 ++++++++--------- src/Tokenizers/PHP.php | 6 +- src/Tokenizers/Tokenizer.php | 4 +- src/Util/Common.php | 60 +++++++++---------- tests/Core/Util/Common/IsCamelCapsTest.php | 38 ++++++------ 9 files changed, 116 insertions(+), 116 deletions(-) diff --git a/autoload.php b/autoload.php index e61c472fb1..3f39599746 100644 --- a/autoload.php +++ b/autoload.php @@ -61,11 +61,11 @@ class Autoload * This method only loads classes that exist in the PHP_CodeSniffer namespace. * All other classes are ignored and loaded by subsequent autoloaders. * - * @param string $class The name of the class to load. + * @param string $className The name of the class to load. * * @return bool */ - public static function load($class) + public static function load($className) { // Include the composer autoloader if there is one, but re-register it // so this autoloader runs before the composer one as we need to include @@ -73,7 +73,7 @@ public static function load($class) if (self::$composerAutoloader === null) { // Make sure we don't try to load any of Composer's classes // while the autoloader is being setup. - if (strpos($class, 'Composer\\') === 0) { + if (strpos($className, 'Composer\\') === 0) { return false; } @@ -97,8 +97,8 @@ public static function load($class) $ds = DIRECTORY_SEPARATOR; $path = false; - if (substr($class, 0, 16) === 'PHP_CodeSniffer\\') { - if (substr($class, 0, 22) === 'PHP_CodeSniffer\Tests\\') { + if (substr($className, 0, 16) === 'PHP_CodeSniffer\\') { + if (substr($className, 0, 22) === 'PHP_CodeSniffer\Tests\\') { $isInstalled = !is_dir(__DIR__.$ds.'tests'); if ($isInstalled === false) { $path = __DIR__.$ds.'tests'; @@ -106,23 +106,23 @@ public static function load($class) $path = '@test_dir@'.$ds.'PHP_CodeSniffer'.$ds.'CodeSniffer'; } - $path .= $ds.substr(str_replace('\\', $ds, $class), 22).'.php'; + $path .= $ds.substr(str_replace('\\', $ds, $className), 22).'.php'; } else { - $path = __DIR__.$ds.'src'.$ds.substr(str_replace('\\', $ds, $class), 16).'.php'; + $path = __DIR__.$ds.'src'.$ds.substr(str_replace('\\', $ds, $className), 16).'.php'; } } // See if the composer autoloader knows where the class is. if ($path === false && self::$composerAutoloader !== false) { - $path = self::$composerAutoloader->findFile($class); + $path = self::$composerAutoloader->findFile($className); } // See if the class is inside one of our alternate search paths. if ($path === false) { foreach (self::$searchPaths as $searchPath => $nsPrefix) { - $className = $class; - if ($nsPrefix !== '' && substr($class, 0, strlen($nsPrefix)) === $nsPrefix) { - $className = substr($class, (strlen($nsPrefix) + 1)); + $className = $className; + if ($nsPrefix !== '' && substr($className, 0, strlen($nsPrefix)) === $nsPrefix) { + $className = substr($className, (strlen($nsPrefix) + 1)); } $path = $searchPath.$ds.str_replace('\\', $ds, $className).'.php'; @@ -297,18 +297,18 @@ public static function getLoadedClassName($path) /** * Gets the file path for the given class name. * - * @param string $class The name of the class. + * @param string $className The name of the class. * * @throws \Exception If the class name has not been loaded. * @return string */ - public static function getLoadedFileName($class) + public static function getLoadedFileName($className) { - if (isset(self::$loadedFiles[$class]) === false) { - throw new Exception("Cannot get file name for $class; class has not been included"); + if (isset(self::$loadedFiles[$className]) === false) { + throw new Exception("Cannot get file name for $className; class has not been included"); } - return self::$loadedFiles[$class]; + return self::$loadedFiles[$className]; }//end getLoadedFileName() diff --git a/src/Config.php b/src/Config.php index 52efb227d5..9c149965f9 100644 --- a/src/Config.php +++ b/src/Config.php @@ -1483,12 +1483,12 @@ public function printUsage() /** * Prints out the short usage information for this script. * - * @param bool $return If TRUE, the usage string is returned - * instead of output to screen. + * @param bool $returnOutput If TRUE, the usage string is returned + * instead of output to screen. * * @return string|void */ - public function printShortUsage($return=false) + public function printShortUsage($returnOutput=false) { if (PHP_CODESNIFFER_CBF === true) { $usage = 'Run "phpcbf --help" for usage information'; @@ -1498,7 +1498,7 @@ public function printShortUsage($return=false) $usage .= PHP_EOL.PHP_EOL; - if ($return === true) { + if ($returnOutput === true) { return $usage; } diff --git a/src/Standards/Generic/Sniffs/PHP/DeprecatedFunctionsSniff.php b/src/Standards/Generic/Sniffs/PHP/DeprecatedFunctionsSniff.php index 44efd53afd..580dac548d 100644 --- a/src/Standards/Generic/Sniffs/PHP/DeprecatedFunctionsSniff.php +++ b/src/Standards/Generic/Sniffs/PHP/DeprecatedFunctionsSniff.php @@ -49,17 +49,17 @@ public function __construct() /** * Generates the error or warning for this sniff. * - * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned. - * @param int $stackPtr The position of the forbidden function - * in the token array. - * @param string $function The name of the forbidden function. - * @param string $pattern The pattern used for the match. + * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned. + * @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. * * @return void */ - protected function addError($phpcsFile, $stackPtr, $function, $pattern=null) + protected function addError($phpcsFile, $stackPtr, $functionName, $pattern=null) { - $data = [$function]; + $data = [$functionName]; $error = 'Function %s() has been deprecated'; $type = 'Deprecated'; diff --git a/src/Standards/Generic/Sniffs/PHP/ForbiddenFunctionsSniff.php b/src/Standards/Generic/Sniffs/PHP/ForbiddenFunctionsSniff.php index f77531c989..80647c7e30 100644 --- a/src/Standards/Generic/Sniffs/PHP/ForbiddenFunctionsSniff.php +++ b/src/Standards/Generic/Sniffs/PHP/ForbiddenFunctionsSniff.php @@ -202,17 +202,17 @@ public function process(File $phpcsFile, $stackPtr) /** * Generates the error or warning for this sniff. * - * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned. - * @param int $stackPtr The position of the forbidden function - * in the token array. - * @param string $function The name of the forbidden function. - * @param string $pattern The pattern used for the match. + * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned. + * @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. * * @return void */ - protected function addError($phpcsFile, $stackPtr, $function, $pattern=null) + protected function addError($phpcsFile, $stackPtr, $functionName, $pattern=null) { - $data = [$function]; + $data = [$functionName]; $error = 'The use of function %s() is '; if ($this->error === true) { $type = 'Found'; @@ -223,7 +223,7 @@ protected function addError($phpcsFile, $stackPtr, $function, $pattern=null) } if ($pattern === null) { - $pattern = strtolower($function); + $pattern = strtolower($functionName); } if ($this->forbiddenFunctions[$pattern] !== null) { diff --git a/src/Tokenizers/Comment.php b/src/Tokenizers/Comment.php index c3dc8aa28d..824b9b646e 100644 --- a/src/Tokenizers/Comment.php +++ b/src/Tokenizers/Comment.php @@ -19,35 +19,35 @@ class Comment /** * Splits a single doc block comment token up into something that can be easily iterated over. * - * @param string $string The doc block comment string to parse. + * @param string $comment The doc block comment string to parse. * @param string $eolChar The EOL character to use for splitting strings. * @param int $stackPtr The position of the token in the "new"/final token stream. * * @return array>> */ - public function tokenizeString($string, $eolChar, $stackPtr) + public function tokenizeString($comment, $eolChar, $stackPtr) { if (PHP_CODESNIFFER_VERBOSITY > 1) { StatusWriter::write('*** START COMMENT TOKENIZING ***', 2); } $tokens = []; - $numChars = strlen($string); + $numChars = strlen($comment); /* Doc block comments start with /*, but typically contain an extra star when they are used for function and class comments. */ - $char = ($numChars - strlen(ltrim($string, '/*'))); - $lastChars = substr($string, -2); + $char = ($numChars - strlen(ltrim($comment, '/*'))); + $lastChars = substr($comment, -2); if ($char === $numChars && $lastChars === '*/') { // Edge case: docblock without whitespace or contents. - $openTag = substr($string, 0, -2); - $string = $lastChars; + $openTag = substr($comment, 0, -2); + $comment = $lastChars; } else { - $openTag = substr($string, 0, $char); - $string = ltrim($string, '/*'); + $openTag = substr($comment, 0, $char); + $comment = ltrim($comment, '/*'); } $tokens[$stackPtr] = [ @@ -73,7 +73,7 @@ public function tokenizeString($string, $eolChar, $stackPtr) */ $closeTag = [ - 'content' => substr($string, strlen(rtrim($string, '/*'))), + 'content' => substr($comment, strlen(rtrim($comment, '/*'))), 'code' => T_DOC_COMMENT_CLOSE_TAG, 'type' => 'T_DOC_COMMENT_CLOSE_TAG', 'comment_opener' => $openPtr, @@ -84,7 +84,7 @@ public function tokenizeString($string, $eolChar, $stackPtr) $closeTag['content'] = ''; } - $string = rtrim($string, '/*'); + $string = rtrim($comment, '/*'); /* Process each line of the comment. @@ -181,32 +181,32 @@ public function tokenizeString($string, $eolChar, $stackPtr) /** * Process a single line of a comment. * - * @param string $string The comment string being tokenized. + * @param string $comment The comment string being tokenized. * @param string $eolChar The EOL character to use for splitting strings. * @param int $start The position in the string to start processing. * @param int $end The position in the string to end processing. * * @return array> */ - private function processLine($string, $eolChar, $start, $end) + private function processLine($comment, $eolChar, $start, $end) { $tokens = []; // Collect content padding. - $space = $this->collectWhitespace($string, $start, $end); + $space = $this->collectWhitespace($comment, $start, $end); if ($space !== null) { $tokens[] = $space; $start += strlen($space['content']); } - if (isset($string[$start]) === false) { + if (isset($comment[$start]) === false) { return $tokens; } - if ($string[$start] === '@') { + if ($comment[$start] === '@') { // The content up until the first whitespace is the tag name. $matches = []; - preg_match('/@[^\s]+/', $string, $matches, 0, $start); + preg_match('/@[^\s]+/', $comment, $matches, 0, $start); if (isset($matches[0]) === true && substr(strtolower($matches[0]), 0, 7) !== '@phpcs:' ) { @@ -219,7 +219,7 @@ private function processLine($string, $eolChar, $start, $end) ]; // Then there will be some whitespace. - $space = $this->collectWhitespace($string, $start, $end); + $space = $this->collectWhitespace($comment, $start, $end); if ($space !== null) { $tokens[] = $space; $start += strlen($space['content']); @@ -228,14 +228,14 @@ private function processLine($string, $eolChar, $start, $end) }//end if // Process the rest of the line. - $eol = strpos($string, $eolChar, $start); + $eol = strpos($comment, $eolChar, $start); if ($eol === false) { $eol = $end; } if ($eol > $start) { $tokens[] = [ - 'content' => substr($string, $start, ($eol - $start)), + 'content' => substr($comment, $start, ($eol - $start)), 'code' => T_DOC_COMMENT_STRING, 'type' => 'T_DOC_COMMENT_STRING', ]; @@ -243,7 +243,7 @@ private function processLine($string, $eolChar, $start, $end) if ($eol !== $end) { $tokens[] = [ - 'content' => substr($string, $eol, strlen($eolChar)), + 'content' => substr($comment, $eol, strlen($eolChar)), 'code' => T_DOC_COMMENT_WHITESPACE, 'type' => 'T_DOC_COMMENT_WHITESPACE', ]; @@ -257,21 +257,21 @@ private function processLine($string, $eolChar, $start, $end) /** * Collect consecutive whitespace into a single token. * - * @param string $string The comment string being tokenized. - * @param int $start The position in the string to start processing. - * @param int $end The position in the string to end processing. + * @param string $comment The comment string being tokenized. + * @param int $start The position in the string to start processing. + * @param int $end The position in the string to end processing. * * @return array|null */ - private function collectWhitespace($string, $start, $end) + private function collectWhitespace($comment, $start, $end) { $space = ''; for ($start; $start < $end; $start++) { - if ($string[$start] !== ' ' && $string[$start] !== "\t") { + if ($comment[$start] !== ' ' && $comment[$start] !== "\t") { break; } - $space .= $string[$start]; + $space .= $comment[$start]; } if ($space === '') { diff --git a/src/Tokenizers/PHP.php b/src/Tokenizers/PHP.php index 089d267755..176e70241e 100644 --- a/src/Tokenizers/PHP.php +++ b/src/Tokenizers/PHP.php @@ -531,11 +531,11 @@ class PHP extends Tokenizer * Starts by using token_get_all() but does a lot of extra processing * to insert information about the context of the token. * - * @param string $string The string to tokenize. + * @param string $code The code to tokenize. * * @return array */ - protected function tokenize($string) + protected function tokenize($code) { if (PHP_CODESNIFFER_VERBOSITY > 1) { StatusWriter::write('*** START PHP TOKENIZING ***', 1); @@ -545,7 +545,7 @@ protected function tokenize($string) } } - $tokens = @token_get_all($string); + $tokens = @token_get_all($code); $finalTokens = []; $newStackPtr = 0; diff --git a/src/Tokenizers/Tokenizer.php b/src/Tokenizers/Tokenizer.php index 373e9b456e..303b94bc3e 100644 --- a/src/Tokenizers/Tokenizer.php +++ b/src/Tokenizers/Tokenizer.php @@ -170,11 +170,11 @@ public function getTokens() /** * Creates an array of tokens when given some content. * - * @param string $string The string to tokenize. + * @param string $code The code to tokenize. * * @return array */ - abstract protected function tokenize($string); + abstract protected function tokenize($code); /** diff --git a/src/Util/Common.php b/src/Util/Common.php index 234727a698..7be2a79481 100644 --- a/src/Util/Common.php +++ b/src/Util/Common.php @@ -337,35 +337,35 @@ public static function stripColors($text) /** - * Returns true if the specified string is in the camel caps format. - * - * @param string $string The string to verify. - * @param boolean $classFormat If true, check to see if the string is in the - * class format. Class format strings must start - * with a capital letter and contain no - * underscores. - * @param boolean $public If true, the first character in the string - * must be an a-z character. If false, the - * character must be an underscore. This - * argument is only applicable if $classFormat - * is false. - * @param boolean $strict If true, the string must not have two capital - * letters next to each other. If false, a - * relaxed camel caps policy is used to allow - * for acronyms. + * Returns true if the specified text string is in the camel caps format. + * + * @param string $name The string to verify. + * @param boolean $classFormat If true, check to see if the string is in the + * class format. Class format strings must start + * with a capital letter and contain no + * underscores. + * @param boolean $visibilityPublic If true, the first character in the string + * must be an a-z character. If false, the + * character must be an underscore. This + * argument is only applicable if $classFormat + * is false. + * @param boolean $strict If true, the string must not have two capital + * letters next to each other. If false, a + * relaxed camel caps policy is used to allow + * for acronyms. * * @return boolean */ public static function isCamelCaps( - $string, + $name, $classFormat=false, - $public=true, + $visibilityPublic=true, $strict=true ) { // Check the first character first. if ($classFormat === false) { $legalFirstChar = ''; - if ($public === false) { + if ($visibilityPublic === false) { $legalFirstChar = '[_]'; } @@ -380,28 +380,28 @@ public static function isCamelCaps( $legalFirstChar = '[A-Z]'; } - if (preg_match("/^$legalFirstChar/", $string) === 0) { + if (preg_match("/^$legalFirstChar/", $name) === 0) { return false; } // Check that the name only contains legal characters. $legalChars = 'a-zA-Z0-9'; - if (preg_match("|[^$legalChars]|", substr($string, 1)) > 0) { + if (preg_match("|[^$legalChars]|", substr($name, 1)) > 0) { return false; } if ($strict === true) { // Check that there are not two capital letters next to each other. - $length = strlen($string); + $length = strlen($name); $lastCharWasCaps = $classFormat; for ($i = 1; $i < $length; $i++) { - $ascii = ord($string[$i]); + $ascii = ord($name[$i]); if ($ascii >= 48 && $ascii <= 57) { // The character is a number, so it can't be a capital. $isCaps = false; } else { - if (strtoupper($string[$i]) === $string[$i]) { + if (strtoupper($name[$i]) === $name[$i]) { $isCaps = true; } else { $isCaps = false; @@ -422,23 +422,23 @@ public static function isCamelCaps( /** - * Returns true if the specified string is in the underscore caps format. + * Returns true if the specified text string is in the underscore caps format. * - * @param string $string The string to verify. + * @param string $name The text string to verify. * * @return boolean */ - public static function isUnderscoreName($string) + public static function isUnderscoreName($name) { // If there is whitespace in the name, it can't be valid. - if (strpos($string, ' ') !== false) { + if (strpos($name, ' ') !== false) { return false; } $validName = true; - $nameBits = explode('_', $string); + $nameBits = explode('_', $name); - if (preg_match('|^[A-Z]|', $string) === 0) { + if (preg_match('|^[A-Z]|', $name) === 0) { // Name does not begin with a capital letter. $validName = false; } else { diff --git a/tests/Core/Util/Common/IsCamelCapsTest.php b/tests/Core/Util/Common/IsCamelCapsTest.php index 609334aa6d..ef12b322a8 100644 --- a/tests/Core/Util/Common/IsCamelCapsTest.php +++ b/tests/Core/Util/Common/IsCamelCapsTest.php @@ -379,54 +379,54 @@ public static function dataInvalidClassFormat() /** - * Test invalid class names with the public flag set. + * Test invalid class names with the "visibilityPublic" flag set. * - * Note that the public flag is ignored if the class format + * Note that the visibilityPublic flag is ignored if the class format * flag is set, so these names are all invalid. * - * @param string $name The tested name. - * @param bool $public Value of the $public flag. + * @param string $name The tested name. + * @param bool $visibilityPublic Value of the $visibilityPublic flag. * - * @dataProvider dataInvalidClassFormatWithPublicFlag + * @dataProvider dataInvalidClassFormatWithVisibilityPublicFlag * * @return void */ - public function testInvalidClassFormatWithPublicFlag($name, $public) + public function testInvalidClassFormatWithVisibilityPublicFlag($name, $visibilityPublic) { - $this->assertFalse(Common::isCamelCaps($name, true, $public)); + $this->assertFalse(Common::isCamelCaps($name, true, $visibilityPublic)); - }//end testInvalidClassFormatWithPublicFlag() + }//end testInvalidClassFormatWithVisibilityPublicFlag() /** * Data provider. * - * @see testInvalidClassFormatWithPublicFlag() + * @see testInvalidClassFormatWithVisibilityPublicFlag() * * @return array> */ - public static function dataInvalidClassFormatWithPublicFlag() + public static function dataInvalidClassFormatWithVisibilityPublicFlag() { return [ 'PascalCase string with initial underscore (public)' => [ - 'name' => '_ThisIsCamelCaps', - 'public' => true, + 'name' => '_ThisIsCamelCaps', + 'visibilityPublic' => true, ], 'PascalCase string with initial underscore (private)' => [ - 'name' => '_ThisIsCamelCaps', - 'public' => false, + 'name' => '_ThisIsCamelCaps', + 'visibilityPublic' => false, ], 'empty string (public)' => [ - 'name' => '', - 'public' => true, + 'name' => '', + 'visibilityPublic' => true, ], 'empty string (private)' => [ - 'name' => '', - 'public' => false, + 'name' => '', + 'visibilityPublic' => false, ], ]; - }//end dataInvalidClassFormatWithPublicFlag() + }//end dataInvalidClassFormatWithVisibilityPublicFlag() /**