*/ protected $changedFunctions = ['func_get_arg' => \true, 'func_get_args' => \true, 'debug_backtrace' => \true, 'debug_print_backtrace' => \true]; /** * Tokens to ignore when determining the start of a statement for call to one of the functions. * * @since 9.1.0 * * @var array */ private $ignoreForStartOfStatement = [\T_COMMA, \T_DOUBLE_ARROW, \T_OPEN_SQUARE_BRACKET, \T_OPEN_PARENTHESIS]; /** * Tokens to ignore when determining the start of a statement for a used variable. * * @since 10.0.0 * * @var array */ private $ignoreForStartOfStatementVarUse = [\T_COMMA, \T_DOUBLE_ARROW, \T_OPEN_SQUARE_BRACKET, \T_OPEN_PARENTHESIS, \T_OPEN_SHORT_ARRAY]; /** * Returns an array of tokens this test wants to listen for. * * @since 9.1.0 * * @return array */ public function register() { return [\T_FUNCTION, \T_CLOSURE]; } /** * Processes this test, when one of its tokens is encountered. * * @since 9.1.0 * * @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. * * @return void */ public function process(File $phpcsFile, $stackPtr) { if (ScannedCode::shouldRunOnOrAbove('7.0') === \false) { return; } $tokens = $phpcsFile->getTokens(); if (isset($tokens[$stackPtr]['scope_opener'], $tokens[$stackPtr]['scope_closer']) === \false) { // Abstract function, interface function, live coding or parse error. return; } $scopeOpener = $tokens[$stackPtr]['scope_opener']; $scopeCloser = $tokens[$stackPtr]['scope_closer']; // Does the function declaration have parameters ? $params = FunctionDeclarations::getParameters($phpcsFile, $stackPtr); if (empty($params)) { // No named arguments found, so no risk of them being changed. return; } $paramNames = []; foreach ($params as $param) { $paramNames[] = $param['name']; } $prevNonEmpty = $scopeOpener; for ($i = $scopeOpener + 1; $i < $scopeCloser; $prevNonEmpty = isset(Tokens::$emptyTokens[$tokens[$i]['code']]) ? $prevNonEmpty : $i, $i++) { if ((isset(Collections::closedScopes()[$tokens[$i]['code']]) || $tokens[$i]['code'] === \T_FN) && isset($tokens[$i]['scope_closer'])) { // Skip past nested structures. $i = $tokens[$i]['scope_closer']; continue; } if ($tokens[$i]['code'] !== \T_STRING && $tokens[$i]['code'] !== \T_NAME_FULLY_QUALIFIED) { continue; } $foundFunctionName = \strtolower(\ltrim($tokens[$i]['content'], '\\')); if (isset($this->changedFunctions[$foundFunctionName]) === \false) { // Not one of the target functions. continue; } /* * Ok, so is this really a function call to one of the PHP native functions ? */ $next = $phpcsFile->findNext(Tokens::$emptyTokens, $i + 1, null, \true); if ($next === \false || $tokens[$next]['code'] !== \T_OPEN_PARENTHESIS) { // Live coding, parse error or not a function call. continue; } if ($this->isCallToGlobalFunction($phpcsFile, $i) === \false) { continue; } /* * Check if the function is used as a PHP 8.1+ first class callable. * * Not allowed by PHP for the func_get_arg*() functions, so ignore. * Allowed for the debug_*backtrace() functions, but please don't do this.... */ if (isset($tokens[$next]['parenthesis_closer'])) { $hasEllipsis = $phpcsFile->findNext(Tokens::$emptyTokens, $next + 1, null, \true); if ($hasEllipsis !== \false && $tokens[$hasEllipsis]['code'] === \T_ELLIPSIS) { $isFirstClassCallable = $phpcsFile->findNext(Tokens::$emptyTokens, $hasEllipsis + 1, null, \true); if ($isFirstClassCallable !== \false && $isFirstClassCallable === $tokens[$next]['parenthesis_closer']) { if ($foundFunctionName === 'debug_backtrace' || $foundFunctionName === 'debug_print_backtrace') { $error = 'Since PHP 7.0, functions inspecting arguments, like %1$s(), no longer report the original value as passed to a parameter, but will instead provide the current value. Using this function as a first class callable is a really bad idea.'; $data = [$foundFunctionName]; $phpcsFile->addWarning($error, $i, 'AsFirstClassCallable', $data); } continue; } } } /* * Address some special cases. */ if ($foundFunctionName !== 'func_get_args') { switch ($foundFunctionName) { /* * Check if `debug_(print_)backtrace()` is called with the * `DEBUG_BACKTRACE_IGNORE_ARGS` option. */ case 'debug_backtrace': case 'debug_print_backtrace': $optionsParam = PassedParameters::getParameter($phpcsFile, $i, 1, 'options'); if ($optionsParam !== \false && (\preg_match('`(^|\|)\s*\\\\?DEBUG_BACKTRACE_IGNORE_ARGS`', $optionsParam['clean']) === 1 || $optionsParam['clean'] === '2' || $optionsParam['clean'] === '3')) { // Debug_backtrace() called with ignore args option. continue 2; } break; /* * Collect the necessary information to only throw a notice if the argument * touched/changed is in line with the passed $arg_num. * * Also, we can ignore `func_get_arg()` if the argument offset passed is * higher than the number of named parameters. * * {@internal Note: This does not take calculations into account! * Should be exceptionally rare and can - if needs be - be addressed at a later stage.} */ case 'func_get_arg': $positionParam = PassedParameters::getParameter($phpcsFile, $i, 1, 'position'); if ($positionParam !== \false) { $number = $phpcsFile->findNext(\T_LNUMBER, $positionParam['start'], $positionParam['end'] + 1); if ($number !== \false) { $argNumber = (int) Numbers::getCompleteNumber($phpcsFile, $number)['decimal']; if (isset($paramNames[$argNumber]) === \false) { // Requesting a non-named additional parameter. Ignore. continue 2; } } } break; } } else { /* * Check if the call to func_get_args() happens to be in an array_slice() or * array_splice() with an $offset higher than the number of named parameters. * In that case, we can ignore it. * * {@internal Note: This does not take offset calculations into account! * Should be exceptionally rare and can - if needs be - be addressed at a later stage.} */ $lastParenthesesOpener = Parentheses::getLastOpener($phpcsFile, $i); if ($lastParenthesesOpener !== \false) { $maybeFunctionCall = $phpcsFile->findPrevious(Tokens::$emptyTokens, $lastParenthesesOpener - 1, null, \true); if (($tokens[$maybeFunctionCall]['code'] === \T_STRING || $tokens[$maybeFunctionCall]['code'] === \T_NAME_FULLY_QUALIFIED) && $this->isCallToGlobalFunction($phpcsFile, $maybeFunctionCall) === \true) { $functionNameLc = \strtolower(\ltrim($tokens[$maybeFunctionCall]['content'], '\\')); if ($functionNameLc === 'array_slice' || $functionNameLc === 'array_splice') { // Verify the `func_get_args()` was seen in the correct parameter for this check. $parentFuncArrayParam = PassedParameters::getParameter($phpcsFile, $maybeFunctionCall, 1, 'array'); if ($parentFuncArrayParam !== \false && $parentFuncArrayParam['start'] <= $i && $i <= $parentFuncArrayParam['end']) { $parentFuncOffsetParam = PassedParameters::getParameter($phpcsFile, $maybeFunctionCall, 2, 'offset'); if ($parentFuncOffsetParam !== \false) { $offsetValue = TokenGroup::isNumber($phpcsFile, $parentFuncOffsetParam['start'], $parentFuncOffsetParam['end']); if (\is_int($offsetValue)) { $normalizedOffsetValue = $offsetValue >= 0 ? $offsetValue : \count($paramNames) + $offsetValue; if (isset($paramNames[$normalizedOffsetValue]) === \false) { // Requesting non-named additional parameters. Ignore. continue; } $targetLength = null; $parentFuncLengthParam = PassedParameters::getParameter($phpcsFile, $maybeFunctionCall, 3, 'length'); if ($parentFuncLengthParam !== \false) { $lengthValue = TokenGroup::isNumber($phpcsFile, $parentFuncLengthParam['start'], $parentFuncLengthParam['end']); if (\is_int($lengthValue) && $lengthValue !== 0) { $targetLength = $lengthValue; } } // Slice starts at a named argument, but we know which params are being accessed. $paramNamesSubset = \array_slice($paramNames, $offsetValue, $targetLength); } } } } } } unset($lastParenthesesOpener, $functionNameLc); } /* * For debug_backtrace(), check if the result is being dereferenced and if so, * whether the `args` index is used. * I.e. whether `$index` in `debug_backtrace()[$stackFrame][$index]` is a string * with the content `args`. * * Note: We already know that $next is the open parenthesis of the function call. */ if ($foundFunctionName === 'debug_backtrace' && isset($tokens[$next]['parenthesis_closer'])) { $afterParenthesis = $phpcsFile->findNext(Tokens::$emptyTokens, $tokens[$next]['parenthesis_closer'] + 1, null, \true); if ($tokens[$afterParenthesis]['code'] === \T_OPEN_SQUARE_BRACKET && isset($tokens[$afterParenthesis]['bracket_closer'])) { $afterStackFrame = $phpcsFile->findNext(Tokens::$emptyTokens, $tokens[$afterParenthesis]['bracket_closer'] + 1, null, \true); if ($tokens[$afterStackFrame]['code'] === \T_OPEN_SQUARE_BRACKET && isset($tokens[$afterStackFrame]['bracket_closer'])) { $arrayIndex = $phpcsFile->findNext(\T_CONSTANT_ENCAPSED_STRING, $afterStackFrame + 1, $tokens[$afterStackFrame]['bracket_closer']); if ($arrayIndex !== \false && TextStrings::stripQuotes($tokens[$arrayIndex]['content']) !== 'args') { continue; } } } } /* * Only check for variables before the start of the statement to * prevent false positives on the return value of the function call * being assigned to one of the parameters, i.e.: * `$param = func_get_args();`. */ $startOfStatement = BCFile::findStartOfStatement($phpcsFile, $i, $this->ignoreForStartOfStatement); /* * Ok, so we've found one of the target functions in the right scope. * Now, let's check if any of the passed parameters were touched. */ $scanResult = 'clean'; $variableToken = null; $listsSeen = []; for ($j = $scopeOpener + 1; $j < $startOfStatement; $j++) { if (isset(Collections::closedScopes()[$tokens[$j]['code']]) && isset($tokens[$j]['scope_closer'])) { // Skip past nested structures. $j = $tokens[$j]['scope_closer']; continue; } // Ignore return, exit and throw statements completely. if ($tokens[$j]['code'] === \T_RETURN || $tokens[$j]['code'] === \T_EXIT || $tokens[$j]['code'] === \T_THROW) { $j = BCFile::findEndOfStatement($phpcsFile, $j); continue; } // Ignore use of any of the passed parameters in isset() or empty(). if ($tokens[$j]['code'] === \T_ISSET || $tokens[$j]['code'] === \T_EMPTY) { $nextNonEmpty = $phpcsFile->findNext(Tokens::$emptyTokens, $j + 1, null, \true); if ($nextNonEmpty !== \false && isset($tokens[$nextNonEmpty]['parenthesis_closer'])) { $j = $tokens[$nextNonEmpty]['parenthesis_closer']; continue; } } // Keep track of the long/short lists structures seen. if (isset(Collections::listOpenTokensBC()[$tokens[$j]['code']])) { $listOpenClose = Lists::getOpenClose($phpcsFile, $j); if ($listOpenClose !== \false) { // Store in reverse order so we always have the last seen list first. $listOpenClose['list_token'] = $j; \array_unshift($listsSeen, $listOpenClose); } } if ($tokens[$j]['code'] !== \T_VARIABLE) { continue; } if ($foundFunctionName === 'func_get_arg' && isset($argNumber)) { if (isset($paramNames[$argNumber]) && $tokens[$j]['content'] !== $paramNames[$argNumber]) { // Different param than the one requested by func_get_arg(). continue; } } elseif ($foundFunctionName === 'func_get_args' && isset($paramNamesSubset)) { if (\in_array($tokens[$j]['content'], $paramNamesSubset, \true) === \false) { // Different param than the ones requested by func_get_args(). continue; } } elseif (\in_array($tokens[$j]['content'], $paramNames, \true) === \false) { // Variable is not one of the function parameters. continue; } /* * Check if this is a variable in a list structure. * * For variables in a list, we need to: * - Flag assignments. * - Ignore list keys. */ if ($listsSeen !== []) { foreach ($listsSeen as $openClose) { if ($openClose['opener'] < $j && $j < $openClose['closer']) { $listInfo = Lists::getAssignments($phpcsFile, $openClose['list_token']); foreach ($listInfo as $listItem) { if ($listItem['is_empty'] === \false && $listItem['is_nested_list'] === \false) { if ($listItem['assignment_token'] === $j) { // We found a definite assignment within a list. $scanResult = 'error'; $variableToken = $j; break 3; } if (isset($listItem['key_token'], $listItem['key_end_token']) && $listItem['key_token'] <= $j && $j <= $listItem['key_end_token']) { // The variable is used in the key for a list. We can safely disregard it. continue 3; } } } break; } } } $beforeVar = $phpcsFile->findPrevious(Tokens::$emptyTokens, $j - 1, null, \true); $startOfVariableStatement = BCFile::findStartOfStatement($phpcsFile, $j, $this->ignoreForStartOfStatementVarUse); /* * Check if this is only a plain assignment. If so, ignore. * * A "plain assignment" for the purposes of this check is defined as: * - Variable is not nested in parenthesis, i.e. not used in a potential function call. * - Not preceded by a reference operator. * - Has an assignment operator before it and none after. * * Additionally, we also check if this is a list assignment and if so, if there are no reference * assignments within the list. * If there are no references in the list, we can ignore this assignment as plain. */ if (empty($tokens[$j]['nested_parenthesis']) === \true && $beforeVar !== \false && Operators::isReference($phpcsFile, $beforeVar) === \false && ($tokens[$startOfVariableStatement]['code'] === \T_VARIABLE || isset(Collections::listOpenTokensBC()[$tokens[$startOfVariableStatement]['code']]))) { // If this was a list assignment, we need to make sure there are no reference assignments. $listHasReferenceAssignment = \false; if (isset(Collections::listOpenTokensBC()[$tokens[$startOfVariableStatement]['code']])) { foreach ($listsSeen as $openClose) { if ($openClose['list_token'] === $startOfVariableStatement) { $listHasReferenceAssignment = $this->doesListHaveReferenceAssignments($phpcsFile, $openClose['list_token']); break; } } } $endOfVariableStatement = $phpcsFile->findNext([\T_SEMICOLON, \T_CLOSE_TAG], $j + 1); $lastAssignmentOperator = $phpcsFile->findPrevious(Tokens::$assignmentTokens, $endOfVariableStatement - 1, $startOfVariableStatement); if ($lastAssignmentOperator !== \false && $lastAssignmentOperator < $j && $listHasReferenceAssignment === \false) { continue; } } /* * Check if this variable is used in a control structure condition. * * For the purposes of this check, this type of usage is non-problematic if: * - The variable is the only thing in the control structure condition, * so no analysis of more complex comparisons. * - If the control structure is a `foreach()`, the variable is used in the "before as" part. * - And we're going to ignore `for()` structures as too complex. */ $inForeach = Context::inForeachCondition($phpcsFile, $j); if ($inForeach === 'beforeAs') { // Safe to ignore. continue; } elseif ($inForeach === 'afterAs') { // We know this is an assignment, so throw an error. $scanResult = 'error'; $variableToken = $j; break; } if (Parentheses::getLastOwner($phpcsFile, $j, \T_CATCH) !== \false) { // The only variable in a catch statement is the one being assigned to, so throw an error. $scanResult = 'error'; $variableToken = $j; break; } $afterVar = $phpcsFile->findNext(Tokens::$emptyTokens, $j + 1, null, \true); $lastParenthesesOpener = Parentheses::getLastOpener($phpcsFile, $j); if ($lastParenthesesOpener !== \false && isset($tokens[$lastParenthesesOpener]['parenthesis_closer']) === \true && Parentheses::isOwnerIn($phpcsFile, $lastParenthesesOpener, Collections::controlStructureTokens()) && $beforeVar === $lastParenthesesOpener && $afterVar === $tokens[$lastParenthesesOpener]['parenthesis_closer']) { continue; } // Check for $obj::class, which can be safely ignored. if ($tokens[$afterVar]['code'] === \T_DOUBLE_COLON) { $nextAfterAfterVar = $phpcsFile->findNext(Tokens::$emptyTokens, $afterVar + 1, null, \true); if ($tokens[$nextAfterAfterVar]['code'] === \T_STRING && \strtolower($tokens[$nextAfterAfterVar]['content']) === 'class') { continue; } } /* * Ok, so we've found a variable which was passed as one of the parameters. * Now, is this variable being changed, i.e. incremented, decremented, unset * or assigned something ? */ $scanResult = 'warning'; if (isset($variableToken) === \false) { $variableToken = $j; } if ($beforeVar !== \false && isset(Collections::incrementDecrementOperators()[$tokens[$beforeVar]['code']])) { // Variable is being (pre-)incremented/decremented. $scanResult = 'error'; $variableToken = $j; break; } if ($afterVar === \false) { // Shouldn't be possible, but just in case. continue; // @codeCoverageIgnore } if (isset(Collections::incrementDecrementOperators()[$tokens[$afterVar]['code']])) { // Variable is being (post-)incremented/decremented. $scanResult = 'error'; $variableToken = $j; break; } if (Context::inUnset($phpcsFile, $j)) { // Variable is being unset. $scanResult = 'error'; $variableToken = $j; break; } if ($tokens[$afterVar]['code'] === \T_OPEN_SQUARE_BRACKET && isset($tokens[$afterVar]['bracket_closer'])) { // Skip past array access on the variable. while (($afterVar = $phpcsFile->findNext(Tokens::$emptyTokens, $tokens[$afterVar]['bracket_closer'] + 1, null, \true)) !== \false) { if ($tokens[$afterVar]['code'] !== \T_OPEN_SQUARE_BRACKET || isset($tokens[$afterVar]['bracket_closer']) === \false) { break; } } } if (isset(Tokens::$assignmentTokens[$tokens[$afterVar]['code']]) && $tokens[$afterVar]['code'] !== \T_COALESCE_EQUAL) { // Variable is being assigned something. $scanResult = 'error'; $variableToken = $j; break; } } unset($argNumber, $paramNamesSubset); if ($scanResult === 'clean') { continue; } $error = 'Since PHP 7.0, functions inspecting arguments, like %1$s(), no longer report the original value as passed to a parameter, but will instead provide the current value. The parameter "%2$s" was %4$s on line %3$s.'; $data = [$foundFunctionName, $tokens[$variableToken]['content'], $tokens[$variableToken]['line']]; if ($scanResult === 'error') { $data[] = 'changed'; $phpcsFile->addError($error, $i, 'Changed', $data); } elseif ($scanResult === 'warning') { $data[] = 'used, and possibly changed (by reference),'; $phpcsFile->addWarning($error, $i, 'NeedsInspection', $data); } unset($variableToken); } } /** * Check if a `T_STRING` token represents a function call to a global function. * * Note: not 100% precise, but should be sufficient for now. At a later point in * time there will probably be a PHPCSUtils function for this. * * @since 10.0.0 * * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned. * @param int $stackPtr The position of the potential function call * token in the stack. * * @return bool */ private function isCallToGlobalFunction(File $phpcsFile, $stackPtr) { if (Context::inAttribute($phpcsFile, $stackPtr) === \true) { // Class instantiation in attribute, not function call. return \false; } $tokens = $phpcsFile->getTokens(); $prevNonEmpty = $phpcsFile->findPrevious(Tokens::$emptyTokens, $stackPtr - 1, null, \true); if (isset(Collections::objectOperators()[$tokens[$prevNonEmpty]['code']]) === \true) { // Method call. return \false; } if ($tokens[$prevNonEmpty]['code'] === \T_NEW || $tokens[$prevNonEmpty]['code'] === \T_FUNCTION) { return \false; } if ($tokens[$prevNonEmpty]['code'] === \T_NS_SEPARATOR) { $prevPrevToken = $phpcsFile->findPrevious(Tokens::$emptyTokens, $prevNonEmpty - 1, null, \true); if ($tokens[$prevPrevToken]['code'] === \T_STRING || $tokens[$prevPrevToken]['code'] === \T_NAMESPACE) { // Namespaced function. return \false; } } return \true; } /** * Check if there are any reference assignments in a list structure. * * @since 10.0.0 * * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned. * @param int $stackPtr The position of the list token. * * @return bool */ private function doesListHaveReferenceAssignments(File $phpcsFile, $stackPtr) { $listInfo = Lists::getAssignments($phpcsFile, $stackPtr); foreach ($listInfo as $listItem) { if ($listItem['assign_by_reference'] === \true) { return \true; } if ($listItem['is_nested_list'] === \true && $this->doesListHaveReferenceAssignments($phpcsFile, $listItem['assignment_token']) === \true) { return \true; } } return \false; } }