24632078366

Committed 19 Apr 2026 02:39PM UTC coverage: 94.489% (+0.8%) from 93.732%

Build # 24632078366

Build Type

Pull #360

github

Committed by

sirbrillig

Commit Message

Simplify getUseIndexForUseImport using findContainingOpeningBracket()

Replaces the manual findPrevious call with an exclusion list with the
existing findContainingOpeningBracket() abstraction, and simplifies the
second findPrevious to skip only empty tokens.

Pull Request Pull Request #360: Migrate to PHPCSUtils

Coverage Stats

67 of 70 new or added lines in 2 files covered. (95.71%)

8 existing lines in 2 files now uncovered.

1749 of 1851 relevant lines covered (94.49%)

138.7 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

95.14

/VariableAnalysis/Sniffs/CodeAnalysis/VariableAnalysisSniff.php

<?php

namespace VariableAnalysis\Sniffs\CodeAnalysis;

use VariableAnalysis\Lib\ScopeInfo;
use VariableAnalysis\Lib\ScopeType;
use VariableAnalysis\Lib\VariableInfo;
use VariableAnalysis\Lib\Constants;
use VariableAnalysis\Lib\Helpers;
use VariableAnalysis\Lib\ScopeManager;
use PHP_CodeSniffer\Sniffs\Sniff;
use PHP_CodeSniffer\Files\File;
use PHP_CodeSniffer\Util\Tokens;

class VariableAnalysisSniff implements Sniff
{
        /**
         * The current phpcsFile being checked.
         *
         * @var File|null
         */
        protected $currentFile = null;

        /**
         * @var ScopeManager
         */
        private $scopeManager;

        /**
         * A list of for loops, keyed by the index of their first token in this file.
         *
         * @var array<int, \VariableAnalysis\Lib\ForLoopInfo>
         */
        private $forLoops = [];

        /**
         * A list of enum blocks, keyed by the index of their first token in this file.
         *
         * @var array<int, \VariableAnalysis\Lib\EnumInfo>
         */
        private $enums = [];

        /**
         * A list of custom functions which pass in variables to be initialized by
         * reference (eg `preg_match()`) and therefore should not require those
         * variables to be defined ahead of time. The list is space separated and
         * each entry is of the form `functionName:1,2`. The function name comes
         * first followed by a colon and a comma-separated list of argument numbers
         * (starting from 1) which should be considered variable definitions. The
         * special value `...` in the arguments list will cause all arguments after
         * the last number to be considered variable definitions.
         *
         * @var string|null
         */
        public $sitePassByRefFunctions = null;

        /**
         * If set, allows common WordPress pass-by-reference functions in addition to
         * the standard PHP ones.
         *
         * @var bool
         */
        public $allowWordPressPassByRefFunctions = false;

        /**
         *  Allow exceptions in a catch block to be unused without warning.
         *
         *  @var bool
         */
        public $allowUnusedCaughtExceptions = true;

        /**
         *  Allow function parameters to be unused without provoking unused-var warning.
         *
         *  @var bool
         */
        public $allowUnusedFunctionParameters = false;

        /**
         *  If set, ignores undefined variables in the file scope (the top-level
         *  scope of a file).
         *
         *  @var bool
         */
        public $allowUndefinedVariablesInFileScope = false;

        /**
         *  If set, ignores unused variables in the file scope (the top-level
         *  scope of a file).
         *
         *  @var bool
         */
        public $allowUnusedVariablesInFileScope = false;

        /**
         *  A space-separated list of names of placeholder variables that you want to
         *  ignore from unused variable warnings. For example, to ignore the variables
         *  `$junk` and `$unused`, this could be set to `'junk unused'`.
         *
         *  @var string|null
         */
        public $validUnusedVariableNames = null;

        /**
         *  A PHP regexp string for variables that you want to ignore from unused
         *  variable warnings. For example, to ignore the variables `$_junk` and
         *  `$_unused`, this could be set to `'/^_/'`.
         *
         *  @var string|null
         */
        public $ignoreUnusedRegexp = null;

        /**
         *  A space-separated list of names of placeholder variables that you want to
         *  ignore from undefined variable warnings. For example, to ignore the variables
         *  `$post` and `$undefined`, this could be set to `'post undefined'`.
         *
         *  @var string|null
         */
        public $validUndefinedVariableNames = null;

        /**
         *  A PHP regexp string for variables that you want to ignore from undefined
         *  variable warnings. For example, to ignore the variables `$_junk` and
         *  `$_unused`, this could be set to `'/^_/'`.
         *
         *  @var string|null
         */
        public $validUndefinedVariableRegexp = null;

        /**
         * Allows unused arguments in a function definition if they are
         * followed by an argument which is used.
         *
         *  @var bool
         */
        public $allowUnusedParametersBeforeUsed = true;

        /**
         * If set to true, unused values from the `key => value` syntax
         * in a `foreach` loop will never be marked as unused.
         *
         *  @var bool
         */
        public $allowUnusedForeachVariables = true;

        /**
         * If set to true, unused variables in a function before a require or import
         * statement will not be marked as unused because they may be used in the
         * required file.
         *
         *  @var bool
         */
        public $allowUnusedVariablesBeforeRequire = false;

        /**
         * A cache for getPassByReferenceFunctions
         *
         * @var array<array<int|string>>|null
         */
        private $passByRefFunctionsCache = null;

        public function __construct()
        {
                $this->scopeManager = new ScopeManager();
        }

        /**
         * Decide which tokens to scan.
         *
         * @return (int|string)[]
         */
        #[\Override]
        public function register()
        {
                $types = [
                        T_VARIABLE,
                        T_DOUBLE_QUOTED_STRING,
                        T_HEREDOC,
                        T_CLOSE_CURLY_BRACKET,
                        T_FUNCTION,
                        T_CLOSURE,
                        T_STRING,
                        T_COMMA,
                        T_SEMICOLON,
                        T_CLOSE_PARENTHESIS,
                        T_FOR,
                        T_ENDFOR,
                ];
                if (defined('T_FN')) {
                        $types[] = T_FN;
                }
                if (defined('T_ENUM')) {
                        $types[] = T_ENUM;
                }
                return $types;
        }

        /**
         * @param string $functionName
         *
         * @return array<int|string>
         */
        private function getPassByReferenceFunction($functionName)
        {
                $passByRefFunctions = $this->getPassByReferenceFunctions();
                return isset($passByRefFunctions[$functionName]) ? $passByRefFunctions[$functionName] : [];
        }

        /**
         * @return array<array<int|string>>
         */
        private function getPassByReferenceFunctions()
        {
                if (! is_null($this->passByRefFunctionsCache)) {
                        return $this->passByRefFunctionsCache;
                }
                $passByRefFunctions = Constants::getPassByReferenceFunctions();
                if (!empty($this->sitePassByRefFunctions)) {
                        $lines = Helpers::splitStringToArray('/\s+/', trim($this->sitePassByRefFunctions));
                        foreach ($lines as $line) {
                                list ($function, $args) = explode(':', $line);
                                $passByRefFunctions[$function] = explode(',', $args);
                        }
                }
                if ($this->allowWordPressPassByRefFunctions) {
                        $passByRefFunctions = array_merge($passByRefFunctions, Constants::getWordPressPassByReferenceFunctions());
                }
                $this->passByRefFunctionsCache = $passByRefFunctions;
                return $passByRefFunctions;
        }

        /**
         * Scan and process a token.
         *
         * This is the main processing function of the sniff. Will run on every token
         * for which `register()` returns true.
         *
         * @param File $phpcsFile
         * @param int  $stackPtr
         *
         * @return void
         */
        #[\Override]
        public function process(File $phpcsFile, $stackPtr)
        {
                $tokens = $phpcsFile->getTokens();

                $scopeStartTokenTypes = [
                        T_FUNCTION,
                        T_CLOSURE,
                ];

                $token = $tokens[$stackPtr];

                // Cache the current PHPCS File in an instance variable so it can be more
                // easily accessed in other places which aren't passed the object.
                if ($this->currentFile !== $phpcsFile) {
                        $this->currentFile = $phpcsFile;
                        $this->forLoops = [];
                        $this->enums = [];
                }

                // Add the global scope for the current file to our scope indexes.
                $scopesForFilename = $this->scopeManager->getScopesForFilename($phpcsFile->getFilename());
                if (empty($scopesForFilename)) {
                        $this->scopeManager->recordScopeStartAndEnd($phpcsFile, 0);
                }

                // Find and process variables to perform two jobs: to record variable
                // definition or use, and to report variables as undefined if they are used
                // without having been first defined.
                if ($token['code'] === T_VARIABLE) {
                        $this->processVariable($phpcsFile, $stackPtr);
                }

                // Report variables defined but not used in the current scope as unused
                // variables if the current token closes scopes.
                $this->searchForAndProcessClosingScopesAt($phpcsFile, $stackPtr);

                // Scan variables that were postponed because they exist in the increment
                // expression of a for loop if the current token closes a loop.
                $this->processClosingForLoopsAt($phpcsFile, $stackPtr);

                if ($token['code'] === T_VARIABLE) {
                        return;
                }

                if (($token['code'] === T_DOUBLE_QUOTED_STRING) || ($token['code'] === T_HEREDOC)) {
                        $this->processVariableInString($phpcsFile, $stackPtr);
                        return;
                }
                if (($token['code'] === T_STRING) && ($token['content'] === 'compact')) {
                        $this->processCompact($phpcsFile, $stackPtr);
                        return;
                }

                // Record for loop boundaries so we can delay scanning the third for loop
                // expression until after the loop has been scanned.
                if ($token['code'] === T_FOR) {
                        $this->recordForLoop($phpcsFile, $stackPtr);
                        return;
                }

                // Record enums so we can detect them even before phpcs was able to.
                if ($token['content'] === 'enum') {
                        $enumInfo = Helpers::makeEnumInfo($phpcsFile, $stackPtr);
                        // The token might not actually be an enum so let's avoid returning if
                        // it's not.
                        if ($enumInfo) {
                                $this->enums[$stackPtr] = $enumInfo;
                                return;
                        }
                }

                // If the current token is a call to `get_defined_vars()`, consider that a
                // usage of all variables in the current scope.
                if ($this->isGetDefinedVars($phpcsFile, $stackPtr)) {
                        Helpers::debug('get_defined_vars is being called');
                        $this->markAllVariablesRead($phpcsFile, $stackPtr);
                        return;
                }

                // If the current token starts a scope, record that scope's start and end
                // indexes so that we can determine if variables in that scope are defined
                // and/or used.
                if (
                        in_array($token['code'], $scopeStartTokenTypes, true) ||
                        Helpers::isArrowFunction($phpcsFile, $stackPtr)
                ) {
                        Helpers::debug('found scope condition', $token);
                        $this->scopeManager->recordScopeStartAndEnd($phpcsFile, $stackPtr);
                        return;
                }
        }

        /**
         * Record the boundaries of a for loop.
         *
         * @param File $phpcsFile
         * @param int  $stackPtr
         *
         * @return void
         */
        private function recordForLoop($phpcsFile, $stackPtr)
        {
                $this->forLoops[$stackPtr] = Helpers::makeForLoopInfo($phpcsFile, $stackPtr);
        }

        /**
         * Find scopes closed by a token and process their variables.
         *
         * Calls `processScopeClose()` for each closed scope.
         *
         * @param File $phpcsFile
         * @param int  $stackPtr
         *
         * @return void
         */
        private function searchForAndProcessClosingScopesAt($phpcsFile, $stackPtr)
        {
                $scopeIndicesThisCloses = $this->scopeManager->getScopesForScopeEnd($phpcsFile->getFilename(), $stackPtr);

                $tokens = $phpcsFile->getTokens();
                $token = $tokens[$stackPtr];
                $line = $token['line'];
                foreach ($scopeIndicesThisCloses as $scopeIndexThisCloses) {
                        Helpers::debug('found closing scope at index', $stackPtr, 'line', $line, 'for scopes starting at:', $scopeIndexThisCloses->scopeStartIndex);
                        $this->processScopeClose($phpcsFile, $scopeIndexThisCloses->scopeStartIndex);
                }
        }

        /**
         * Scan variables that were postponed because they exist in the increment expression of a for loop.
         *
         * @param File $phpcsFile
         * @param int  $stackPtr
         *
         * @return void
         */
        private function processClosingForLoopsAt($phpcsFile, $stackPtr)
        {
                $forLoopsThisCloses = [];
                foreach ($this->forLoops as $forLoop) {
                        if ($forLoop->blockEnd === $stackPtr) {
                                $forLoopsThisCloses[] = $forLoop;
                        }
                }

                foreach ($forLoopsThisCloses as $forLoop) {
                        foreach ($forLoop->incrementVariables as $varIndex => $varInfo) {
                                Helpers::debug('processing delayed for loop increment variable at', $varIndex, $varInfo);
                                $this->processVariable($phpcsFile, $varIndex, ['ignore-for-loops' => true]);
                        }
                }
        }

        /**
         * Return true if the token is a call to `get_defined_vars()`.
         *
         * @param File $phpcsFile
         * @param int  $stackPtr
         *
         * @return bool
         */
        protected function isGetDefinedVars(File $phpcsFile, $stackPtr)
        {
                $tokens = $phpcsFile->getTokens();
                $token = $tokens[$stackPtr];
                if (! $token || $token['content'] !== 'get_defined_vars') {
                        return false;
                }
                // Make sure this is a function call
                $parenPointer = $phpcsFile->findNext(Tokens::$emptyTokens, ($stackPtr + 1), null, true);
                if (! $parenPointer || $tokens[$parenPointer]['code'] !== T_OPEN_PARENTHESIS) {
                        return false;
                }
                return true;
        }

        /**
         * @return string
         */
        protected function getFilename()
        {
                return $this->currentFile ? $this->currentFile->getFilename() : 'unknown file';
        }

        /**
         * @param int $currScope
         *
         * @return ScopeInfo
         */
        protected function getOrCreateScopeInfo($currScope)
        {
                $scope = $this->scopeManager->getScopeForScopeStart($this->getFilename(), $currScope);
                if (! $scope) {
                        if (! $this->currentFile) {
                                throw new \Exception('Cannot create scope info; current file is not set.');
                        }
                        $scope = $this->scopeManager->recordScopeStartAndEnd($this->currentFile, $currScope);
                }
                return $scope;
        }

        /**
         * @param string $varName
         * @param int    $currScope
         *
         * @return VariableInfo|null
         */
        protected function getVariableInfo($varName, $currScope)
        {
                $scopeInfo = $this->scopeManager->getScopeForScopeStart($this->getFilename(), $currScope);
                return ($scopeInfo && isset($scopeInfo->variables[$varName])) ? $scopeInfo->variables[$varName] : null;
        }

        /**
         * Returns variable data for a variable at an index.
         *
         * The variable will also be added to the list of variables stored in its
         * scope so that its use or non-use can be reported when those scopes end by
         * `processScopeClose()`.
         *
         * @param string $varName
         * @param int    $currScope
         *
         * @return VariableInfo
         */
        protected function getOrCreateVariableInfo($varName, $currScope)
        {
                Helpers::debug("getOrCreateVariableInfo: starting for '{$varName}'");
                $scopeInfo = $this->getOrCreateScopeInfo($currScope);
                if (isset($scopeInfo->variables[$varName])) {
                        Helpers::debug("getOrCreateVariableInfo: found variable for '{$varName}'", $scopeInfo->variables[$varName]);
                        return $scopeInfo->variables[$varName];
                }
                Helpers::debug("getOrCreateVariableInfo: creating a new variable for '{$varName}' in scope", $scopeInfo);
                $scopeInfo->variables[$varName] = new VariableInfo($varName);
                $validUnusedVariableNames = (empty($this->validUnusedVariableNames))
                ? []
                : Helpers::splitStringToArray('/\s+/', trim($this->validUnusedVariableNames));
                $validUndefinedVariableNames = (empty($this->validUndefinedVariableNames))
                ? []
                : Helpers::splitStringToArray('/\s+/', trim($this->validUndefinedVariableNames));
                if (in_array($varName, $validUnusedVariableNames)) {
                        $scopeInfo->variables[$varName]->ignoreUnused = true;
                }
                if (! empty($this->ignoreUnusedRegexp) && preg_match($this->ignoreUnusedRegexp, $varName) === 1) {
                        $scopeInfo->variables[$varName]->ignoreUnused = true;
                }
                if ($scopeInfo->scopeStartIndex === 0 && $this->allowUndefinedVariablesInFileScope) {
                        $scopeInfo->variables[$varName]->ignoreUndefined = true;
                }
                if (in_array($varName, $validUndefinedVariableNames)) {
                        $scopeInfo->variables[$varName]->ignoreUndefined = true;
                }
                if (! empty($this->validUndefinedVariableRegexp) && preg_match($this->validUndefinedVariableRegexp, $varName) === 1) {
                        $scopeInfo->variables[$varName]->ignoreUndefined = true;
                }
                Helpers::debug("getOrCreateVariableInfo: scope for '{$varName}' is now", $scopeInfo);
                return $scopeInfo->variables[$varName];
        }

        /**
         * Record that a variable has been defined and assigned a value.
         *
         * If a variable has been defined within a scope, it will not be marked as
         * undefined when that variable is later used. If it is not used, it will be
         * marked as unused when that scope ends.
         *
         * Sometimes it's possible to assign something to a variable without
         * definining it (eg: assignment to a reference); in that case, use
         * `markVariableAssignmentWithoutInitialization()`.
         *
         * @param string $varName
         * @param int    $stackPtr
         * @param int    $currScope
         *
         * @return void
         */
        protected function markVariableAssignment($varName, $stackPtr, $currScope)
        {
                Helpers::debug('markVariableAssignment: starting for', $varName);
                $this->markVariableAssignmentWithoutInitialization($varName, $stackPtr, $currScope);
                Helpers::debug('markVariableAssignment: marked as assigned without initialization', $varName);
                $varInfo = $this->getOrCreateVariableInfo($varName, $currScope);
                if (isset($varInfo->firstInitialized) && ($varInfo->firstInitialized <= $stackPtr)) {
                        Helpers::debug('markVariableAssignment: variable is already initialized', $varName);
                        return;
                }
                $varInfo->firstInitialized = $stackPtr;
                Helpers::debug('markVariableAssignment: marked as initialized', $varName);
        }

        /**
         * Record that a variable has been assigned a value.
         *
         * Does not record that a variable has been defined, which is the usual state
         * of affairs. For that, use `markVariableAssignment()`.
         *
         * This is useful for assignments to references.
         *
         * @param string $varName
         * @param int    $stackPtr
         * @param int    $currScope
         *
         * @return void
         */
        protected function markVariableAssignmentWithoutInitialization($varName, $stackPtr, $currScope)
        {
                $varInfo = $this->getOrCreateVariableInfo($varName, $currScope);

                // Is the variable referencing another variable? If so, mark that variable used also.
                if ($varInfo->referencedVariableScope !== null && $varInfo->referencedVariableScope !== $currScope) {
                        Helpers::debug('markVariableAssignmentWithoutInitialization: considering marking referenced variable assigned', $varName);
                        // Don't do this if the referenced variable does not exist; eg: if it's going to be bound at runtime like in array_walk
                        if ($this->getVariableInfo($varInfo->name, $varInfo->referencedVariableScope)) {
                                Helpers::debug('markVariableAssignmentWithoutInitialization: marking referenced variable as assigned also', $varName);
                                $this->markVariableAssignment($varInfo->name, $stackPtr, $varInfo->referencedVariableScope);
                        } else {
                                Helpers::debug('markVariableAssignmentWithoutInitialization: not marking referenced variable assigned', $varName);
                        }
                } else {
                                Helpers::debug('markVariableAssignmentWithoutInitialization: not considering referenced variable', $varName);
                }

                if (empty($varInfo->scopeType)) {
                        $varInfo->scopeType = ScopeType::LOCAL;
                }
                $varInfo->allAssignments[] = $stackPtr;
        }

        /**
         * Record that a variable has been defined within a scope.
         *
         * @param string                                                                                           $varName
         * @param ScopeType::PARAM|ScopeType::BOUND|ScopeType::LOCAL|ScopeType::GLOBALSCOPE|ScopeType::STATICSCOPE $scopeType
         * @param ?string                                                                                          $typeHint
         * @param int                                                                                              $stackPtr
         * @param int                                                                                              $currScope
         * @param ?bool                                                                                            $permitMatchingRedeclaration
         *
         * @return void
         */
        protected function markVariableDeclaration(
                $varName,
                $scopeType,
                $typeHint,
                $stackPtr,
                $currScope,
                $permitMatchingRedeclaration = false
        ) {
                Helpers::debug("marking variable '{$varName}' declared in scope starting at token", $currScope);
                $varInfo = $this->getOrCreateVariableInfo($varName, $currScope);

                if (! empty($varInfo->scopeType)) {
                        if (($permitMatchingRedeclaration === false) || ($varInfo->scopeType !== $scopeType)) {
                                //  Issue redeclaration/reuse warning
                                //  Note: we check off scopeType not firstDeclared, this is so that
                                //    we catch declarations that come after implicit declarations like
                                //    use of a variable as a local.
                                $this->addWarning(
                                        'Redeclaration of %s %s as %s.',
                                        $stackPtr,
                                        'VariableRedeclaration',
                                        [
                                                VariableInfo::$scopeTypeDescriptions[$varInfo->scopeType],
                                                "\${$varName}",
                                                VariableInfo::$scopeTypeDescriptions[$scopeType],
                                        ]
                                );
                        }
                }

                $varInfo->scopeType = $scopeType;
                if (isset($typeHint)) {
                        $varInfo->typeHint = $typeHint;
                }
                if (isset($varInfo->firstDeclared) && ($varInfo->firstDeclared <= $stackPtr)) {
                        Helpers::debug("variable '{$varName}' was already marked declared", $varInfo);
                        return;
                }
                $varInfo->firstDeclared = $stackPtr;
                $varInfo->allAssignments[] = $stackPtr;
                Helpers::debug("variable '{$varName}' marked declared", $varInfo);
        }

        /**
         * @param string   $message
         * @param int      $stackPtr
         * @param string   $code
         * @param string[] $data
         *
         * @return void
         */
        protected function addWarning($message, $stackPtr, $code, $data)
        {
                if (! $this->currentFile) {
                        throw new \Exception('Cannot add warning; current file is not set.');
                }
                $this->currentFile->addWarning(
                        $message,
                        $stackPtr,
                        $code,
                        $data
                );
        }

        /**
         * Record that a variable has been used within a scope.
         *
         * If the variable has not been defined first, this will still mark it used.
         * To display a warning for undefined variables, use
         * `markVariableReadAndWarnIfUndefined()`.
         *
         * @param string $varName
         * @param int    $stackPtr
         * @param int    $currScope
         *
         * @return void
         */
        protected function markVariableRead($varName, $stackPtr, $currScope)
        {
                $varInfo = $this->getOrCreateVariableInfo($varName, $currScope);
                if (isset($varInfo->firstRead) && ($varInfo->firstRead <= $stackPtr)) {
                        return;
                }
                $varInfo->firstRead = $stackPtr;
        }

        /**
         * Return true if a variable is defined within a scope.
         *
         * @param string $varName
         * @param int    $stackPtr
         * @param int    $currScope
         *
         * @return bool
         */
        protected function isVariableUndefined($varName, $stackPtr, $currScope)
        {
                $varInfo = $this->getOrCreateVariableInfo($varName, $currScope);
                Helpers::debug('isVariableUndefined', $varInfo, 'at', $stackPtr);
                if ($varInfo->ignoreUndefined) {
                        return false;
                }
                if (isset($varInfo->firstDeclared) && $varInfo->firstDeclared <= $stackPtr) {
                        return false;
                }
                if (isset($varInfo->firstInitialized) && $varInfo->firstInitialized <= $stackPtr) {
                        return false;
                }
                // If we are inside a for loop increment expression, check to see if the
                // variable was defined inside the for loop.
                foreach ($this->forLoops as $forLoop) {
                        if ($stackPtr > $forLoop->incrementStart && $stackPtr < $forLoop->incrementEnd) {
                                Helpers::debug('isVariableUndefined looking at increment expression for loop', $forLoop);
                                if (
                                        isset($varInfo->firstInitialized)
                                        && $varInfo->firstInitialized > $forLoop->blockStart
                                        && $varInfo->firstInitialized < $forLoop->blockEnd
                                ) {
                                        return false;
                                }
                        }
                }
                // If we are inside a for loop body, check to see if the variable was
                // defined in that loop's third expression.
                foreach ($this->forLoops as $forLoop) {
                        if ($stackPtr > $forLoop->blockStart && $stackPtr < $forLoop->blockEnd) {
                                foreach ($forLoop->incrementVariables as $forLoopVarInfo) {
                                        if ($varInfo === $forLoopVarInfo) {
                                                return false;
                                        }
                                }
                        }
                }
                return true;
        }

        /**
         * Record a variable use and report a warning if the variable is undefined.
         *
         * @param File   $phpcsFile
         * @param string $varName
         * @param int    $stackPtr
         * @param int    $currScope
         *
         * @return void
         */
        protected function markVariableReadAndWarnIfUndefined($phpcsFile, $varName, $stackPtr, $currScope)
        {
                $this->markVariableRead($varName, $stackPtr, $currScope);
                if ($this->isVariableUndefined($varName, $stackPtr, $currScope) === true) {
                        Helpers::debug("variable $varName looks undefined");

                        if (Helpers::isVariableArrayPushShortcut($phpcsFile, $stackPtr)) {
                                $this->warnAboutUndefinedArrayPushShortcut($phpcsFile, $varName, $stackPtr);
                                // Mark the variable as defined if it's of the form `$x[] = 1;`
                                $this->markVariableAssignment($varName, $stackPtr, $currScope);
                                return;
                        }

                        if (Helpers::isVariableInsideUnset($phpcsFile, $stackPtr)) {
                                $this->warnAboutUndefinedUnset($phpcsFile, $varName, $stackPtr);
                                return;
                        }

                        $this->warnAboutUndefinedVariable($phpcsFile, $varName, $stackPtr);
                }
        }

        /**
         * Mark all variables within a scope as being used.
         *
         * This will prevent any of the variables in that scope from being reported
         * as unused.
         *
         * @param File $phpcsFile
         * @param int  $stackPtr
         *
         * @return void
         */
        protected function markAllVariablesRead(File $phpcsFile, $stackPtr)
        {
                $currScope = Helpers::findVariableScope($phpcsFile, $stackPtr);
                if ($currScope === null) {
                        return;
                }
                $scopeInfo = $this->getOrCreateScopeInfo($currScope);
                $count = count($scopeInfo->variables);
                Helpers::debug("marking all $count variables in scope as read");
                foreach ($scopeInfo->variables as $varInfo) {
                        $this->markVariableRead($varInfo->name, $stackPtr, $scopeInfo->scopeStartIndex);
                }
        }

        /**
         * Process a parameter definition if it is inside a function definition.
         *
         * This does not include variables imported by a "use" statement.
         *
         * @param File   $phpcsFile
         * @param int    $stackPtr
         * @param string $varName
         * @param int    $outerScope
         *
         * @return void
         */
        protected function processVariableAsFunctionParameter(File $phpcsFile, $stackPtr, $varName, $outerScope)
        {
                Helpers::debug('processVariableAsFunctionParameter', $stackPtr, $varName);
                $tokens = $phpcsFile->getTokens();

                $functionPtr = Helpers::getFunctionIndexForFunctionParameter($phpcsFile, $stackPtr);
                if (! is_int($functionPtr)) {
                        throw new \Exception("Function index not found for function argument index {$stackPtr}");
                }

                Helpers::debug('processVariableAsFunctionParameter found function definition', $tokens[$functionPtr]);
                $this->markVariableDeclaration($varName, ScopeType::PARAM, null, $stackPtr, $functionPtr);

                // Are we pass-by-reference?
                $referencePtr = $phpcsFile->findPrevious(Tokens::$emptyTokens, $stackPtr - 1, null, true, null, true);
                if (($referencePtr !== false) && ($tokens[$referencePtr]['code'] === T_BITWISE_AND)) {
                        Helpers::debug('processVariableAsFunctionParameter found pass-by-reference to scope', $outerScope);
                        $varInfo = $this->getOrCreateVariableInfo($varName, $functionPtr);
                        $varInfo->referencedVariableScope = $outerScope;
                }

                //  Are we optional with a default?
                if (Helpers::getNextAssignPointer($phpcsFile, $stackPtr) !== null) {
                        Helpers::debug('processVariableAsFunctionParameter optional with default');
                        $this->markVariableAssignment($varName, $stackPtr, $functionPtr);
                }

                // Are we using constructor promotion? If so, that counts as both definition and use.
                if (Helpers::isConstructorPromotion($phpcsFile, $stackPtr)) {
                        Helpers::debug('processVariableAsFunctionParameter constructor promotion');
                        $this->markVariableRead($varName, $stackPtr, $outerScope);
                }
        }

        /**
         * Process a variable definition if it is inside a function's "use" import.
         *
         * @param File   $phpcsFile
         * @param int    $stackPtr
         * @param string $varName
         * @param int    $outerScope The start of the scope outside the function definition
         *
         * @return void
         */
        protected function processVariableAsUseImportDefinition(File $phpcsFile, $stackPtr, $varName, $outerScope)
        {
                $tokens = $phpcsFile->getTokens();

                Helpers::debug('processVariableAsUseImportDefinition', $stackPtr, $varName, $outerScope);

                $endOfArgsPtr = $phpcsFile->findPrevious([T_CLOSE_PARENTHESIS], $stackPtr - 1, null);
                if (! is_int($endOfArgsPtr)) {
                        throw new \Exception("Arguments index not found for function use index {$stackPtr} when processing variable {$varName}");
                }
                $functionPtr = Helpers::getFunctionIndexForFunctionParameter($phpcsFile, $endOfArgsPtr);
                if (! is_int($functionPtr)) {
                        throw new \Exception("Function index not found for function use index {$stackPtr} (using {$endOfArgsPtr}) when processing variable {$varName}");
                }

                // Use is both a read (in the enclosing scope) and a define (in the function scope)
                $this->markVariableRead($varName, $stackPtr, $outerScope);

                // If it's undefined in the enclosing scope, the use is wrong
                if ($this->isVariableUndefined($varName, $stackPtr, $outerScope) === true) {
                        Helpers::debug("variable '{$varName}' in function definition looks undefined in scope", $outerScope);
                        $this->warnAboutUndefinedVariable($phpcsFile, $varName, $stackPtr);
                        return;
                }

                $this->markVariableDeclaration($varName, ScopeType::BOUND, null, $stackPtr, $functionPtr);
                $this->markVariableAssignment($varName, $stackPtr, $functionPtr);

                // Are we pass-by-reference? If so, then any assignment to the variable in
                // the function scope also should count for the enclosing scope.
                $referencePtr = $phpcsFile->findPrevious(Tokens::$emptyTokens, $stackPtr - 1, null, true, null, true);
                if (is_int($referencePtr) && $tokens[$referencePtr]['code'] === T_BITWISE_AND) {
                        Helpers::debug("variable '{$varName}' in function definition looks passed by reference");
                        $varInfo = $this->getOrCreateVariableInfo($varName, $functionPtr);
                        $varInfo->referencedVariableScope = $outerScope;
                }
        }

        /**
         * Process a class property that is being defined.
         *
         * Property definitions are ignored currently because all property access is
         * legal, even to undefined properties.
         *
         * Can be called for any token and will return false if the variable is not
         * of this type.
         *
         * @param File $phpcsFile
         * @param int  $stackPtr
         *
         * @return bool
         */
        protected function processVariableAsClassProperty(File $phpcsFile, $stackPtr)
        {
                // Make sure we are not in a class method before assuming it's a property.
                $tokens = $phpcsFile->getTokens();

                /** @var array{conditions?: (int|string)[], content?: string}|null */
                $token = $tokens[$stackPtr];
                if ($token && !empty($token['conditions']) && !empty($token['content']) && !Helpers::areConditionsWithinFunctionBeforeClass($token)) {
                        return Helpers::areAnyConditionsAClass($phpcsFile, $stackPtr);
                }
                return false;
        }

        /**
         * Process a variable that is being accessed inside a catch block.
         *
         * Can be called for any token and will return false if the variable is not
         * of this type.
         *
         * @param File   $phpcsFile
         * @param int    $stackPtr
         * @param string $varName
         * @param int    $currScope
         *
         * @return bool
         */
        protected function processVariableAsCatchBlock(File $phpcsFile, $stackPtr, $varName, $currScope)
        {
                $tokens = $phpcsFile->getTokens();

                // Are we a catch block parameter?
                $openPtr = Helpers::findContainingOpeningBracket($phpcsFile, $stackPtr);
                if ($openPtr === null) {
                        return false;
                }

                $catchPtr = $phpcsFile->findPrevious(Tokens::$emptyTokens, $openPtr - 1, null, true, null, true);
                if (($catchPtr !== false) && ($tokens[$catchPtr]['code'] === T_CATCH)) {
                        // Scope of the exception var is actually the function, not just the catch block.
                        $this->markVariableDeclaration($varName, ScopeType::LOCAL, null, $stackPtr, $currScope, true);
                        $this->markVariableAssignment($varName, $stackPtr, $currScope);
                        if ($this->allowUnusedCaughtExceptions) {
                                $varInfo = $this->getOrCreateVariableInfo($varName, $currScope);
                                $varInfo->ignoreUnused = true;
                        }
                        return true;
                }
                return false;
        }

        /**
         * Process a variable that is being accessed as a member of `$this`.
         *
         * Looks for variables of the form `$this->myVariable`.
         *
         * Can be called for any token and will return false if the variable is not
         * of this type.
         *
         * @param File   $phpcsFile
         * @param int    $stackPtr
         * @param string $varName
         *
         * @return bool
         */
        protected function processVariableAsThisWithinClass(File $phpcsFile, $stackPtr, $varName)
        {
                $tokens = $phpcsFile->getTokens();
                $token  = $tokens[$stackPtr];

                // Are we $this within a class?
                if (($varName !== 'this') || empty($token['conditions'])) {
                        return false;
                }

                // Handle enums specially since their condition may not exist in old phpcs.
                $inEnum = false;
                foreach ($this->enums as $enum) {
                        if ($stackPtr > $enum->blockStart && $stackPtr < $enum->blockEnd) {
                                $inEnum = true;
                        }
                }

                $inFunction = false;
                foreach (array_reverse($token['conditions'], true) as $scopeCode) {
                        //  $this within a closure is valid
                        if ($scopeCode === T_CLOSURE && $inFunction === false) {
                                return true;
                        }

                        $classlikeCodes = [T_CLASS, T_ANON_CLASS, T_TRAIT];
                        if (defined('T_ENUM')) {
                                $classlikeCodes[] = T_ENUM;
                        }
                        if (in_array($scopeCode, $classlikeCodes, true)) {
                                return true;
                        }

                        if ($scopeCode === T_FUNCTION && $inEnum) {
                                return true;
                        }

                        // Handle nested function declarations.
                        if ($scopeCode === T_FUNCTION) {
                                if ($inFunction === true) {
                                        break;
                                }

                                $inFunction = true;
                        }
                }

                return false;
        }

        /**
         * Process a superglobal variable that is being accessed.
         *
         * Can be called for any token and will return false if the variable is not
         * of this type.
         *
         * @param string $varName
         *
         * @return bool
         */
        protected function processVariableAsSuperGlobal($varName)
        {
                $superglobals = [
                        'GLOBALS',
                        '_SERVER',
                        '_GET',
                        '_POST',
                        '_FILES',
                        '_COOKIE',
                        '_SESSION',
                        '_REQUEST',
                        '_ENV',
                        'argv',
                        'argc',
                        'http_response_header',
                        'HTTP_RAW_POST_DATA',
                ];
                // Are we a superglobal variable?
                return (in_array($varName, $superglobals, true));
        }

        /**
         * Process a variable that is being accessed with static syntax.
         *
         * That is, this will record the use of a variable of the form
         * `MyClass::$myVariable` or `self::$myVariable`.
         *
         * Can be called for any token and will return false if the variable is not
         * of this type.
         *
         * @param File $phpcsFile
         * @param int  $stackPtr
         *
         * @return bool
         */
        protected function processVariableAsStaticMember(File $phpcsFile, $stackPtr)
        {
                $tokens = $phpcsFile->getTokens();

                $doubleColonPtr = $phpcsFile->findPrevious(Tokens::$emptyTokens, $stackPtr - 1, null, true);
                if ($doubleColonPtr === false || $tokens[$doubleColonPtr]['code'] !== T_DOUBLE_COLON) {
                        return false;
                }
                $classNamePtr = $phpcsFile->findPrevious(Tokens::$emptyTokens, $doubleColonPtr - 1, null, true);
                $staticReferences = [
                        T_STRING,
                        T_SELF,
                        T_PARENT,
                        T_STATIC,
                        T_VARIABLE,
                ];
                if ($classNamePtr === false || ! in_array($tokens[$classNamePtr]['code'], $staticReferences, true)) {
                        return false;
                }
                // "When calling static methods, the function call is stronger than the
                // static property operator" so look for a function call.
                $parenPointer = $phpcsFile->findNext(Tokens::$emptyTokens, ($stackPtr + 1), null, true);
                if ($parenPointer !== false && $tokens[$parenPointer]['code'] === T_OPEN_PARENTHESIS) {
                        return false;
                }
                return true;
        }

        /**
         * @param File   $phpcsFile
         * @param int    $stackPtr
         * @param string $varName
         *
         * @return bool
         */
        protected function processVariableAsStaticOutsideClass(File $phpcsFile, $stackPtr, $varName)
        {
                // Are we refering to self:: outside a class?

                $tokens = $phpcsFile->getTokens();

                /** @var array{conditions?: (int|string)[], content?: string}|null */
                $token = $tokens[$stackPtr];

                $doubleColonPtr = $phpcsFile->findPrevious(Tokens::$emptyTokens, $stackPtr - 1, null, true);
                if ($doubleColonPtr === false || $tokens[$doubleColonPtr]['code'] !== T_DOUBLE_COLON) {
                        return false;
                }
                $classNamePtr = $phpcsFile->findPrevious(Tokens::$emptyTokens, $doubleColonPtr - 1, null, true);
                if ($classNamePtr === false) {
                        return false;
                }
                $code = $tokens[$classNamePtr]['code'];
                $staticReferences = [
                        T_SELF,
                        T_STATIC,
                ];
                if (! in_array($code, $staticReferences, true)) {
                        return false;
                }
                $errorClass = $code === T_SELF ? 'SelfOutsideClass' : 'StaticOutsideClass';
                $staticRefType = $code === T_SELF ? 'self::' : 'static::';
                if ($token && !empty($token['content']) && Helpers::areAnyConditionsAClass($phpcsFile, $stackPtr)) {
                        return false;
                }
                $phpcsFile->addError(
                        "Use of {$staticRefType}%s outside class definition.",
                        $stackPtr,
                        $errorClass,
                        ["\${$varName}"]
                );
                return true;
        }

        /**
         * Process a variable that is being assigned.
         *
         * This will record that the variable has been defined within a scope so that
         * later we can determine if it it unused and we can guarantee that any
         * future uses of the variable are not using an undefined variable.
         *
         * References (on either side of an assignment) behave differently and this
         * function handles those cases as well.
         *
         * @param File   $phpcsFile
         * @param int    $stackPtr
         * @param string $varName
         * @param int    $currScope
         *
         * @return void
         */
        protected function processVariableAsAssignment(File $phpcsFile, $stackPtr, $varName, $currScope)
        {
                Helpers::debug("processVariableAsAssignment: starting for '{$varName}'");
                $assignPtr = Helpers::getNextAssignPointer($phpcsFile, $stackPtr);
                if (! is_int($assignPtr)) {
                        return;
                }

                // If the right-hand-side of the assignment to this variable is a reference
                // variable, then this variable is a reference to that one, and as such any
                // assignment to this variable (except another assignment by reference,
                // which would change the binding) has a side effect of changing the
                // referenced variable and therefore should count as both an assignment and
                // a read.
                $tokens = $phpcsFile->getTokens();
                $referencePtr = $phpcsFile->findNext(Tokens::$emptyTokens, $assignPtr + 1, null, true, null, true);
                if (is_int($referencePtr) && $tokens[$referencePtr]['code'] === T_BITWISE_AND) {
                        Helpers::debug("processVariableAsAssignment: found reference variable for '{$varName}'");
                        $varInfo = $this->getOrCreateVariableInfo($varName, $currScope);
                        // If the variable was already declared, but was not yet read, it is
                        // unused because we're about to change the binding; that is, unless we
                        // are inside a conditional block because in that case the condition may
                        // never activate.
                        $scopeInfo = $this->getOrCreateScopeInfo($currScope);
                        $conditionPointer = Helpers::getClosestConditionPositionIfBeforeOtherConditions($tokens[$referencePtr]['conditions']);
                        $lastAssignmentPtr = $varInfo->firstDeclared;
                        if (! $conditionPointer && $lastAssignmentPtr) {
                                Helpers::debug("processVariableAsAssignment: considering close of scope for '{$varName}' due to reference reassignment");
                                $this->processScopeCloseForVariable($phpcsFile, $varInfo, $scopeInfo);
                        }
                        if ($conditionPointer && $lastAssignmentPtr && $conditionPointer < $lastAssignmentPtr) {
                                // We may be inside a condition but the last assignment was also inside this condition.
                                Helpers::debug("processVariableAsAssignment: considering close of scope for '{$varName}' due to reference reassignment ignoring recent condition");
                                $this->processScopeCloseForVariable($phpcsFile, $varInfo, $scopeInfo);
                        }
                        if ($conditionPointer && $lastAssignmentPtr && $conditionPointer > $lastAssignmentPtr) {
                                Helpers::debug("processVariableAsAssignment: not considering close of scope for '{$varName}' due to reference reassignment because it is conditional");
                        }
                        // The referenced variable may have a different name, but we don't
                        // actually need to mark it as used in this case because the act of this
                        // assignment will mark it used on the next token.
                        $varInfo->referencedVariableScope = $currScope;
                        $this->markVariableDeclaration($varName, ScopeType::LOCAL, null, $stackPtr, $currScope, true);
                        // An assignment to a reference is a binding and should not count as
                        // initialization since it doesn't change any values.
                        $this->markVariableAssignmentWithoutInitialization($varName, $stackPtr, $currScope);
                        return;
                }

                Helpers::debug('processVariableAsAssignment: marking as assignment in scope', $currScope);
                $this->markVariableAssignment($varName, $stackPtr, $currScope);

                // If the left-hand-side of the assignment (the variable we are examining)
                // is itself a reference, then that counts as a read as well as a write.
                $varInfo = $this->getOrCreateVariableInfo($varName, $currScope);
                if ($varInfo->isDynamicReference) {
                        Helpers::debug('processVariableAsAssignment: also marking as a use because variable is a reference');
                        $this->markVariableRead($varName, $stackPtr, $currScope);
                }
        }

        /**
         * Processes variables destructured from an array using shorthand list assignment.
         *
         * This will record the definition and assignment of variables defined using
         * the format:
         *
         * ```
         * [ $foo, $bar, $baz ] = $ary;
         * ```
         *
         * Can be called for any token and will return false if the variable is not
         * of this type.
         *
         * @param File   $phpcsFile
         * @param int    $stackPtr
         * @param string $varName
         * @param int    $currScope
         *
         * @return bool
         */
        protected function processVariableAsListShorthandAssignment(File $phpcsFile, $stackPtr, $varName, $currScope)
        {
                // OK, are we within a [ ... ] construct?
                $openPtr = Helpers::findContainingOpeningSquareBracket($phpcsFile, $stackPtr);
                if (! is_int($openPtr)) {
                        return false;
                }

                // OK, we're a [ ... ] construct... are we being assigned to?
                $assignments = Helpers::getListAssignments($phpcsFile, $openPtr);
                if (! $assignments) {
                        return false;
                }
                $matchingAssignment = array_reduce($assignments, function ($thisAssignment, $assignment) use ($stackPtr) {
                        if ($assignment === $stackPtr) {
                                return $assignment;
                        }
                        return $thisAssignment;
                });
                if (! $matchingAssignment) {
                        return false;
                }

                // Yes, we're being assigned.
                $this->markVariableAssignment($varName, $stackPtr, $currScope);
                return true;
        }

        /**
         * Processes variables destructured from an array using list assignment.
         *
         * This will record the definition and assignment of variables defined using
         * the format:
         *
         * ```
         * list( $foo, $bar, $baz ) = $ary;
         * ```
         *
         * Can be called for any token and will return false if the variable is not
         * of this type.
         *
         * @param File   $phpcsFile
         * @param int    $stackPtr
         * @param string $varName
         * @param int    $currScope
         *
         * @return bool
         */
        protected function processVariableAsListAssignment(File $phpcsFile, $stackPtr, $varName, $currScope)
        {
                $tokens = $phpcsFile->getTokens();

                // OK, are we within a list (...) construct?
                $openPtr = Helpers::findContainingOpeningBracket($phpcsFile, $stackPtr);
                if ($openPtr === null) {
                        return false;
                }

                $prevPtr = $phpcsFile->findPrevious(Tokens::$emptyTokens, $openPtr - 1, null, true, null, true);
                if ((is_bool($prevPtr)) || ($tokens[$prevPtr]['code'] !== T_LIST)) {
                        return false;
                }

                // OK, we're a list (...) construct... are we being assigned to?
                $assignments = Helpers::getListAssignments($phpcsFile, $prevPtr);
                if (! $assignments) {
                        return false;
                }
                $matchingAssignment = array_reduce($assignments, function ($thisAssignment, $assignment) use ($stackPtr) {
                        if ($assignment === $stackPtr) {
                                return $assignment;
                        }
                        return $thisAssignment;
                });
                if (! $matchingAssignment) {
                        return false;
                }

                // Yes, we're being assigned.
                $this->markVariableAssignment($varName, $stackPtr, $currScope);
                return true;
        }

        /**
         * Process a variable being defined (imported, really) with the `global` keyword.
         *
         * Can be called for any token and will return false if the variable is not
         * of this type.
         *
         * @param File   $phpcsFile
         * @param int    $stackPtr
         * @param string $varName
         * @param int    $currScope
         *
         * @return bool
         */
        protected function processVariableAsGlobalDeclaration(File $phpcsFile, $stackPtr, $varName, $currScope)
        {
                $tokens = $phpcsFile->getTokens();

                // Are we a global declaration?
                // Search backwards for first token that isn't whitespace/comment, comma or variable.
                $ignore             = Tokens::$emptyTokens;
                $ignore[T_VARIABLE] = T_VARIABLE;
                $ignore[T_COMMA]    = T_COMMA;

                $globalPtr = $phpcsFile->findPrevious($ignore, $stackPtr - 1, null, true, null, true);
                if (($globalPtr === false) || ($tokens[$globalPtr]['code'] !== T_GLOBAL)) {
                        return false;
                }

                // It's a global declaration.
                $this->markVariableDeclaration($varName, ScopeType::GLOBALSCOPE, null, $stackPtr, $currScope);
                return true;
        }

        /**
         * Process a variable as a static declaration within a function.
         *
         * Specifically, this looks for variable definitions of the form `static
         * $foo = 'hello';` or `static int $foo;` inside a function definition.
         *
         * This will not operate on variables that are written in a class definition
         * outside of a function like `static $foo;` or `public static ?int $foo =
         * 'bar';` because class properties (static or instance) are currently not
         * tracked by this sniff. This is because a class property might be unused
         * inside the class, but used outside the class (we cannot easily know if it
         * is unused); this is also because it's common and legal to define class
         * properties when they are assigned and that assignment can happen outside a
         * class (we cannot easily know if the use of a property is undefined). These
         * sorts of checks are better performed by static analysis tools that can see
         * a whole project rather than a linter which can only easily see a file or
         * some lines.
         *
         * If found, such a variable will be marked as declared (and possibly
         * assigned, if it includes an initial value) within the scope of the
         * function body.
         *
         * This will not operate on variables that use late static binding
         * (`static::$foobar`) or the parameters of static methods even though they
         * include the word `static` in the same statement.
         *
         * This only finds the defintions of static variables. Their use is handled
         * by `processVariableAsStaticMember()`.
         *
         * Can be called for any token and will return false if the variable is not
         * of this type.
         *
         * @param File   $phpcsFile
         * @param int    $stackPtr
         * @param string $varName
         * @param int    $currScope
         *
         * @return bool
         */
        protected function processVariableAsStaticDeclaration(File $phpcsFile, $stackPtr, $varName, $currScope)
        {
                $tokens = $phpcsFile->getTokens();

                // Search backwards for a `static` keyword that occurs before the start of the statement.
                $startOfStatement = $phpcsFile->findPrevious([T_SEMICOLON, T_OPEN_CURLY_BRACKET, T_FN_ARROW, T_OPEN_PARENTHESIS], $stackPtr - 1, null, false, null, true);
                $staticPtr = $phpcsFile->findPrevious([T_STATIC], $stackPtr - 1, null, false, null, true);
                if (! is_int($startOfStatement)) {
                        $startOfStatement = 1;
                }
                if (! is_int($staticPtr)) {
                        return false;
                }
                // PHPCS is bad at finding the start of statements so we have to do it ourselves.
                if ($staticPtr < $startOfStatement) {
                        return false;
                }

                // Is the 'static' keyword an anonymous static function declaration? If so,
                // this is not a static variable declaration.
                $tokenAfterStatic = $phpcsFile->findNext(Tokens::$emptyTokens, $staticPtr + 1, null, true, null, true);
                $functionTokenTypes = [
                        T_FUNCTION,
                        T_CLOSURE,
                        T_FN,
                ];
                if (is_int($tokenAfterStatic) && in_array($tokens[$tokenAfterStatic]['code'], $functionTokenTypes, true)) {
                        return false;
                }

                // Is the token inside function parameters? If so, this is not a static
                // declaration because we must be inside a function body.
                if (Helpers::isTokenFunctionParameter($phpcsFile, $stackPtr)) {
                        return false;
                }

                // Is the token inside a function call? If so, this is not a static
                // declaration.
                if (Helpers::isTokenInsideFunctionCallArgument($phpcsFile, $stackPtr)) {
                        return false;
                }

                // Is the keyword a late static binding? If so, this isn't the static
                // keyword we're looking for, but since static:: isn't allowed in a
                // compile-time constant, we also know we can't be part of a static
                // declaration anyway, so there's no need to look any further.
                $lateStaticBindingPtr = $phpcsFile->findNext(T_WHITESPACE, $staticPtr + 1, null, true, null, true);
                if (($lateStaticBindingPtr !== false) && ($tokens[$lateStaticBindingPtr]['code'] === T_DOUBLE_COLON)) {
                        return false;
                }

                $this->markVariableDeclaration($varName, ScopeType::STATICSCOPE, null, $stackPtr, $currScope);
                if (Helpers::getNextAssignPointer($phpcsFile, $stackPtr) !== null) {
                        $this->markVariableAssignment($varName, $stackPtr, $currScope);
                }
                return true;
        }

        /**
         * @param File   $phpcsFile
         * @param int    $stackPtr
         * @param string $varName
         * @param int    $currScope
         *
         * @return bool
         */
        protected function processVariableAsForeachLoopVar(File $phpcsFile, $stackPtr, $varName, $currScope)
        {
                $tokens = $phpcsFile->getTokens();

                // Are we a foreach loopvar?
                $openParenPtr = Helpers::findContainingOpeningBracket($phpcsFile, $stackPtr);
                if (! is_int($openParenPtr)) {
                        return false;
                }
                $foreachPtr = Helpers::getIntOrNull($phpcsFile->findPrevious(Tokens::$emptyTokens, $openParenPtr - 1, null, true));
                if (! is_int($foreachPtr)) {
                        return false;
                }
                if ($tokens[$foreachPtr]['code'] === T_LIST) {
                        $openParenPtr = Helpers::findContainingOpeningBracket($phpcsFile, $foreachPtr);
                        if (! is_int($openParenPtr)) {
                                return false;
                        }
                        $foreachPtr = Helpers::getIntOrNull($phpcsFile->findPrevious(Tokens::$emptyTokens, $openParenPtr - 1, null, true));
                        if (! is_int($foreachPtr)) {
                                return false;
                        }
                }
                if ($tokens[$foreachPtr]['code'] !== T_FOREACH) {
                        return false;
                }

                // Is there an 'as' token between us and the foreach?
                if ($phpcsFile->findPrevious(T_AS, $stackPtr - 1, $openParenPtr) === false) {
                        return false;
                }
                $this->markVariableAssignment($varName, $stackPtr, $currScope);
                $varInfo = $this->getOrCreateVariableInfo($varName, $currScope);

                // Is this the value of a key => value foreach?
                if ($phpcsFile->findPrevious(T_DOUBLE_ARROW, $stackPtr - 1, $openParenPtr) !== false) {
                        $varInfo->isForeachLoopAssociativeValue = true;
                }

                // Are we pass-by-reference?
                $referencePtr = $phpcsFile->findPrevious(Tokens::$emptyTokens, $stackPtr - 1, null, true, null, true);
                if (($referencePtr !== false) && ($tokens[$referencePtr]['code'] === T_BITWISE_AND)) {
                        Helpers::debug('processVariableAsForeachLoopVar: found foreach loop variable assigned by reference');
                        $varInfo->isDynamicReference = true;
                }

                return true;
        }

        /**
         * @param File   $phpcsFile
         * @param int    $stackPtr
         * @param string $varName
         * @param int    $currScope
         *
         * @return bool
         */
        protected function processVariableAsPassByReferenceFunctionCall(File $phpcsFile, $stackPtr, $varName, $currScope)
        {
                $tokens = $phpcsFile->getTokens();

                // Are we pass-by-reference to known pass-by-reference function?
                $functionPtr = Helpers::findFunctionCall($phpcsFile, $stackPtr);
                if ($functionPtr === null || ! isset($tokens[$functionPtr])) {
                        return false;
                }

                // Is our function a known pass-by-reference function?
                $functionName = $tokens[$functionPtr]['content'];

                // In PHPCS 4.x, T_NAME_FULLY_QUALIFIED, T_NAME_QUALIFIED, and T_NAME_RELATIVE
                // tokens contain the full namespaced name. Extract just the base name for the
                // first check so that 'my_function' in the config can match '\My\Namespace\my_function'.
                $functionBaseName = $functionName;
                if ($tokens[$functionPtr]['code'] === T_NAME_FULLY_QUALIFIED) {
                        $lastBackslashPos = strrpos($functionName, '\\');
                        if ($lastBackslashPos !== false) {
                                $functionBaseName = substr($functionName, $lastBackslashPos + 1);
                        }
                } elseif ($tokens[$functionPtr]['code'] === T_NAME_QUALIFIED) {
                        $lastBackslashPos = strrpos($functionName, '\\');
                        if ($lastBackslashPos !== false) {
                                $functionBaseName = substr($functionName, $lastBackslashPos + 1);
                        }
                } elseif ($tokens[$functionPtr]['code'] === T_NAME_RELATIVE) {
                        $lastBackslashPos = strrpos($functionName, '\\');
                        if ($lastBackslashPos !== false) {
                                $functionBaseName = substr($functionName, $lastBackslashPos + 1);
                        }
                }

                // Ensure we have a string (should always be true, but helps static analyzers).
                if (! is_string($functionBaseName) || $functionBaseName === '') {
                        return false;
                }

                $refArgs = $this->getPassByReferenceFunction($functionBaseName);
                if (! $refArgs) {
                        // Check again with the fully namespaced function name.
                        $functionName = Helpers::getFunctionNameWithNamespace($phpcsFile, $functionPtr);
                        if (! $functionName) {
                                return false;
                        }
                        $refArgs = $this->getPassByReferenceFunction($functionName);
                        if (! $refArgs) {
                                return false;
                        }
                }

                $argPtrs = Helpers::findFunctionCallArguments($phpcsFile, $stackPtr);

                // We're within a function call arguments list, find which arg we are.
                $argPos = false;
                foreach ($argPtrs as $idx => $param) {
                        if ($stackPtr >= $param['start'] && $stackPtr <= $param['end']) {
                                $argPos = $idx;
                                break;
                        }
                }
                if ($argPos === false) {
                        return false;
                }
                if (!in_array($argPos, $refArgs)) {
                        // Our arg wasn't mentioned explicitly, are we after an elipsis catch-all?
                        $elipsis = array_search('...', $refArgs);
                        if ($elipsis === false) {
                                return false;
                        }
                        $elipsis = (int)$elipsis;
                        if ($argPos < $refArgs[$elipsis - 1]) {
                                return false;
                        }
                }

                // Our argument position matches that of a pass-by-ref argument,
                // check that we're the only part of the argument expression.
                $param = $argPtrs[$argPos];
                for ($ptr = (int)$param['start']; $ptr <= (int)$param['end']; $ptr++) {
                        if ($ptr === $stackPtr) {
                                continue;
                        }
                        if (isset(Tokens::$emptyTokens[$tokens[$ptr]['code']]) === false) {
                                return false;
                        }
                }

                // Just us, we can mark it as a write.
                $this->markVariableAssignment($varName, $stackPtr, $currScope);
                // It's a read as well for purposes of used-variables.
                $this->markVariableRead($varName, $stackPtr, $currScope);
                return true;
        }

        /**
         * @param File   $phpcsFile
         * @param int    $stackPtr
         * @param string $varName
         * @param int    $currScope
         *
         * @return bool
         */
        protected function processVariableAsSymbolicObjectProperty(File $phpcsFile, $stackPtr, $varName, $currScope)
        {
                $tokens = $phpcsFile->getTokens();

                // Are we a symbolic object property/function derefeference?
                // Search backwards for first token that isn't whitespace, is it a "->" operator?
                $objectOperatorPtr = $phpcsFile->findPrevious(Tokens::$emptyTokens, $stackPtr - 1, null, true, null, true);
                if (($objectOperatorPtr === false) || ($tokens[$objectOperatorPtr]['code'] !== T_OBJECT_OPERATOR)) {
                        return false;
                }

                $this->markVariableReadAndWarnIfUndefined($phpcsFile, $varName, $stackPtr, $currScope);
                return true;
        }

        /**
         * Process a normal variable in the code.
         *
         * Most importantly, this function determines if the variable use is a "read"
         * (using the variable for something) or a "write" (an assignment) or,
         * sometimes, both at once.
         *
         * It also determines the scope of the variable (where it begins and ends).
         *
         * Using these two pieces of information, we can determine if the variable is
         * being used ("read") without having been defined ("write").
         *
         * We can also determine, once the scan has hit the end of a scope, if any of
         * the variables within that scope have been defined ("write") without being
         * used ("read"). That behavior, however, happens in the `processScopeClose()`
         * function using the data gathered by this function.
         *
         * Some variables are used in more complex ways, so there are other similar
         * functions to this one, like `processVariableInString`, and
         * `processCompact`. They have the same purpose as this function, though.
         *
         * If the 'ignore-for-loops' option is true, we will ignore the special
         * processing for the increment variables of for loops. This will prevent
         * infinite loops.
         *
         * @param File                           $phpcsFile The PHP_CodeSniffer file where this token was found.
         * @param int                            $stackPtr  The position where the token was found.
         * @param array<string, bool|string|int> $options   See above.
         *
         * @return void
         */
        protected function processVariable(File $phpcsFile, $stackPtr, $options = [])
        {
                $tokens = $phpcsFile->getTokens();
                $token  = $tokens[$stackPtr];

                // Get the name of the variable.
                $varName = Helpers::normalizeVarName($token['content']);
                Helpers::debug("examining token for variable '{$varName}' on line {$token['line']}", $token);

                // Find the start of the current scope.
                $currScope = Helpers::findVariableScope($phpcsFile, $stackPtr);
                if ($currScope === null) {
                        Helpers::debug('no scope found');
                        return;
                }
                Helpers::debug("start of scope for variable '{$varName}' is", $currScope);

                // Determine if variable is being assigned ("write") or used ("read").

                // Read methods that preempt assignment:
                //   Are we a $object->$property type symbolic reference?

                // Possible assignment methods:
                //   Is a mandatory function/closure parameter
                //   Is an optional function/closure parameter with non-null value
                //   Is closure use declaration of a variable defined within containing scope
                //   catch (...) block start
                //   $this within a class.
                //   $GLOBALS, $_REQUEST, etc superglobals.
                //   $var part of class::$var static member
                //   Assignment via =
                //   Assignment via list (...) =
                //   Declares as a global
                //   Declares as a static
                //   Assignment via foreach (... as ...) { }
                //   Pass-by-reference to known pass-by-reference function

                // Are we inside the third expression of a for loop? Store such variables
                // for processing after the loop ends by `processClosingForLoopsAt()`.
                if (empty($options['ignore-for-loops'])) {
                        $forLoop = Helpers::getForLoopForIncrementVariable($stackPtr, $this->forLoops);
                        if ($forLoop) {
                                Helpers::debug('found variable inside for loop third expression');
                                $varInfo = $this->getOrCreateVariableInfo($varName, $currScope);
                                $forLoop->incrementVariables[$stackPtr] = $varInfo;
                                return;
                        }
                }

                // Are we a $object->$property type symbolic reference?
                if ($this->processVariableAsSymbolicObjectProperty($phpcsFile, $stackPtr, $varName, $currScope)) {
                        Helpers::debug('found symbolic object property');
                        return;
                }

                // Are we a function or closure parameter?
                if (Helpers::isTokenFunctionParameter($phpcsFile, $stackPtr)) {
                        Helpers::debug('found function definition parameter');
                        $this->processVariableAsFunctionParameter($phpcsFile, $stackPtr, $varName, $currScope);
                        return;
                }

                // Are we a variable being imported into a function's scope with "use"?
                if (Helpers::isTokenInsideFunctionUseImport($phpcsFile, $stackPtr)) {
                        Helpers::debug('found use scope import definition');
                        $this->processVariableAsUseImportDefinition($phpcsFile, $stackPtr, $varName, $currScope);
                        return;
                }

                // Are we a catch parameter?
                if ($this->processVariableAsCatchBlock($phpcsFile, $stackPtr, $varName, $currScope)) {
                        Helpers::debug('found catch block');
                        return;
                }

                // Are we $this within a class?
                if ($this->processVariableAsThisWithinClass($phpcsFile, $stackPtr, $varName)) {
                        Helpers::debug('found this usage within a class');
                        return;
                }

                // Are we a $GLOBALS, $_REQUEST, etc superglobal?
                if ($this->processVariableAsSuperGlobal($varName)) {
                        Helpers::debug('found superglobal');
                        return;
                }

                // Check for static members used outside a class
                if ($this->processVariableAsStaticOutsideClass($phpcsFile, $stackPtr, $varName)) {
                        Helpers::debug('found static usage outside of class');
                        return;
                }

                // $var part of class::$var static member
                if ($this->processVariableAsStaticMember($phpcsFile, $stackPtr)) {
                        Helpers::debug('found static member');
                        return;
                }

                if ($this->processVariableAsClassProperty($phpcsFile, $stackPtr)) {
                        Helpers::debug('found class property definition');
                        return;
                }

                // Is the next non-whitespace an assignment?
                if (Helpers::isTokenInsideAssignmentLHS($phpcsFile, $stackPtr)) {
                        Helpers::debug('found assignment');
                        $this->processVariableAsAssignment($phpcsFile, $stackPtr, $varName, $currScope);
                        if (Helpers::isTokenInsideAssignmentRHS($phpcsFile, $stackPtr) || Helpers::isTokenInsideFunctionCallArgument($phpcsFile, $stackPtr)) {
                                Helpers::debug("found assignment that's also inside an expression");
                                $this->markVariableRead($varName, $stackPtr, $currScope);
                                return;
                        }
                        return;
                }

                // OK, are we within a list (...) = construct?
                if ($this->processVariableAsListAssignment($phpcsFile, $stackPtr, $varName, $currScope)) {
                        Helpers::debug('found list assignment');
                        return;
                }

                // OK, are we within a [...] = construct?
                if ($this->processVariableAsListShorthandAssignment($phpcsFile, $stackPtr, $varName, $currScope)) {
                        Helpers::debug('found list shorthand assignment');
                        return;
                }

                // Are we a global declaration?
                if ($this->processVariableAsGlobalDeclaration($phpcsFile, $stackPtr, $varName, $currScope)) {
                        Helpers::debug('found global declaration');
                        return;
                }

                // Are we a static declaration?
                if ($this->processVariableAsStaticDeclaration($phpcsFile, $stackPtr, $varName, $currScope)) {
                        Helpers::debug('found static declaration');
                        return;
                }

                // Are we a foreach loopvar?
                if ($this->processVariableAsForeachLoopVar($phpcsFile, $stackPtr, $varName, $currScope)) {
                        Helpers::debug('found foreach loop variable');
                        return;
                }

                // Are we pass-by-reference to known pass-by-reference function?
                if ($this->processVariableAsPassByReferenceFunctionCall($phpcsFile, $stackPtr, $varName, $currScope)) {
                        Helpers::debug('found pass by reference');
                        return;
                }

                // Are we a numeric variable used for constructs like preg_replace?
                if (Helpers::isVariableANumericVariable($varName)) {
                        Helpers::debug('found numeric variable');
                        return;
                }

                if (Helpers::isVariableInsideElseCondition($phpcsFile, $stackPtr) || Helpers::isVariableInsideElseBody($phpcsFile, $stackPtr)) {
                        Helpers::debug('found variable inside else condition or body');
                        $this->processVaribleInsideElse($phpcsFile, $stackPtr, $varName, $currScope);
                        return;
                }

                // Are we an isset or empty call?
                if (Helpers::isVariableInsideIssetOrEmpty($phpcsFile, $stackPtr)) {
                        Helpers::debug('found isset or empty');
                        $this->markVariableRead($varName, $stackPtr, $currScope);
                        return;
                }

                // OK, we don't appear to be a write to the var, assume we're a read.
                Helpers::debug('looks like a variable read');
                $this->markVariableReadAndWarnIfUndefined($phpcsFile, $varName, $stackPtr, $currScope);
        }

        /**
         * @param File   $phpcsFile
         * @param int    $stackPtr
         * @param string $varName
         * @param int    $currScope
         *
         * @return void
         */
        protected function processVaribleInsideElse(File $phpcsFile, $stackPtr, $varName, $currScope)
        {
                // Find all assignments to this variable inside the current scope.
                $varInfo = $this->getOrCreateVariableInfo($varName, $currScope);
                $allAssignmentIndices = array_unique($varInfo->allAssignments);
                // Find the attached 'if' and 'elseif' block start and end indices.
                $blockIndices = Helpers::getAttachedBlockIndicesForElse($phpcsFile, $stackPtr);

                // If all of the assignments are within the previous attached blocks, then warn about undefined.
                $tokens = $phpcsFile->getTokens();
                $assignmentsInsideAttachedBlocks = [];
                foreach ($allAssignmentIndices as $index) {
                        foreach ($blockIndices as $blockIndex) {
                                $blockToken = $tokens[$blockIndex];
                                Helpers::debug('for variable inside else, looking at assignment', $index, 'at block index', $blockIndex, 'which is token', $blockToken);
                                if (isset($blockToken['scope_opener']) && isset($blockToken['scope_closer'])) {
                                        $scopeOpener = $blockToken['scope_opener'];
                                        $scopeCloser = $blockToken['scope_closer'];
                                } else {
                                        // If the `if` statement has no scope, it is probably inline, which
                                        // means its scope is from the end of the condition up until the next
                                        // semicolon
                                        $scopeOpener = isset($blockToken['parenthesis_closer']) ? $blockToken['parenthesis_closer'] : $blockIndex + 1;
                                        $scopeCloser = $phpcsFile->findNext([T_SEMICOLON], $scopeOpener);
                                        if (! $scopeCloser) {
                                                throw new \Exception("Cannot find scope for if condition block at index {$stackPtr} while examining variable {$varName}");
                                        }
                                }
                                Helpers::debug('for variable inside else, looking at scope', $index, 'between', $scopeOpener, 'and', $scopeCloser);
                                if (Helpers::isIndexInsideScope($index, $scopeOpener, $scopeCloser)) {
                                        $assignmentsInsideAttachedBlocks[] = $index;
                                }
                        }
                }

                if (count($assignmentsInsideAttachedBlocks) === count($allAssignmentIndices)) {
                        if (! $varInfo->ignoreUndefined) {
                                Helpers::debug("variable $varName inside else looks undefined");
                                $this->warnAboutUndefinedVariable($phpcsFile, $varName, $stackPtr);
                        }
                        return;
                }

                Helpers::debug('looks like a variable read inside else');
                $this->markVariableReadAndWarnIfUndefined($phpcsFile, $varName, $stackPtr, $currScope);
        }

        /**
         * Called to process variables found in double quoted strings.
         *
         * Note that there may be more than one variable in the string, which will
         * result only in one call for the string.
         *
         * @param File $phpcsFile The PHP_CodeSniffer file where this token was found.
         * @param int  $stackPtr  The position where the double quoted string was found.
         *
         * @return void
         */
        protected function processVariableInString(File $phpcsFile, $stackPtr)
        {
                $tokens = $phpcsFile->getTokens();
                $token  = $tokens[$stackPtr];

                $regexp = Constants::getDoubleQuotedVarRegexp();
                if (! empty($regexp) && !preg_match_all($regexp, $token['content'], $matches)) {
                        Helpers::debug('processVariableInString: no variables found', $token);
                        return;
                }
                Helpers::debug('examining token for variable in string', $token);

                if (empty($matches)) {
                        Helpers::debug('processVariableInString: no variables found after search', $token);
                        return;
                }
                foreach ($matches[1] as $varName) {
                        $varName = Helpers::normalizeVarName($varName);

                        // Are we $this within a class?
                        if ($this->processVariableAsThisWithinClass($phpcsFile, $stackPtr, $varName)) {
                                continue;
                        }

                        if ($this->processVariableAsSuperGlobal($varName)) {
                                continue;
                        }

                        // Are we a numeric variable used for constructs like preg_replace?
                        if (Helpers::isVariableANumericVariable($varName)) {
                                continue;
                        }

                        $currScope = Helpers::findVariableScope($phpcsFile, $stackPtr, $varName);
                        if ($currScope === null) {
                                continue;
                        }

                        $this->markVariableReadAndWarnIfUndefined($phpcsFile, $varName, $stackPtr, $currScope);
                }
        }

        /**
         * Called to process variables named in a call to compact().
         *
         * @param File $phpcsFile The PHP_CodeSniffer file where this token was found.
         * @param int  $stackPtr  The position where the call to compact() was found.
         *
         * @return void
         */
        protected function processCompact(File $phpcsFile, $stackPtr)
        {
                Helpers::debug("processCompact at {$stackPtr}");
                $arguments = Helpers::findFunctionCallArguments($phpcsFile, $stackPtr);
                $variables = Helpers::getVariablesInsideCompact($phpcsFile, $stackPtr, $arguments);
                foreach ($variables as $variable) {
                        $currScope = Helpers::findVariableScope($phpcsFile, $stackPtr, $variable->name);
                        if ($currScope === null) {
                                continue;
                        }
                        $variablePosition = $variable->firstRead ? $variable->firstRead : $stackPtr;
                        $this->markVariableReadAndWarnIfUndefined($phpcsFile, $variable->name, $variablePosition, $currScope);
                }
        }

        /**
         * Called to process the end of a scope.
         *
         * Note that although triggered by the closing curly brace of the scope,
         * $stackPtr is the scope conditional, not the closing curly brace.
         *
         * @param File $phpcsFile The PHP_CodeSniffer file where this token was found.
         * @param int  $stackPtr  The position of the scope conditional.
         *
         * @return void
         */
        protected function processScopeClose(File $phpcsFile, $stackPtr)
        {
                Helpers::debug("processScopeClose at {$stackPtr}");
                $scopeInfo = $this->scopeManager->getScopeForScopeStart($phpcsFile->getFilename(), $stackPtr);
                if (is_null($scopeInfo)) {
                        return;
                }
                foreach ($scopeInfo->variables as $varInfo) {
                        $this->processScopeCloseForVariable($phpcsFile, $varInfo, $scopeInfo);
                }
        }

        /**
         * Warn about an unused variable if it has not been used within a scope.
         *
         * @param File         $phpcsFile
         * @param VariableInfo $varInfo
         * @param ScopeInfo    $scopeInfo
         *
         * @return void
         */
        protected function processScopeCloseForVariable(File $phpcsFile, VariableInfo $varInfo, ScopeInfo $scopeInfo)
        {
                Helpers::debug('processScopeCloseForVariable', $varInfo);
                if ($varInfo->ignoreUnused || isset($varInfo->firstRead)) {
                        return;
                }
                if ($this->allowUnusedFunctionParameters && $varInfo->scopeType === ScopeType::PARAM) {
                        return;
                }
                if ($this->allowUnusedParametersBeforeUsed && $varInfo->scopeType === ScopeType::PARAM && Helpers::areFollowingArgumentsUsed($varInfo, $scopeInfo)) {
                        Helpers::debug("variable '{$varInfo->name}' at end of scope has unused following args");
                        return;
                }
                if ($this->allowUnusedForeachVariables && $varInfo->isForeachLoopAssociativeValue) {
                        return;
                }
                if ($varInfo->referencedVariableScope !== null && isset($varInfo->firstInitialized)) {
                        Helpers::debug("variable '{$varInfo->name}' at end of scope is a reference and so counts as used");
                        // If we're pass-by-reference then it's a common pattern to
                        // use the variable to return data to the caller, so any
                        // assignment also counts as "variable use" for the purposes
                        // of "unused variable" warnings.
                        return;
                }
                if ($varInfo->scopeType === ScopeType::GLOBALSCOPE && isset($varInfo->firstInitialized)) {
                        Helpers::debug("variable '{$varInfo->name}' at end of scope is a global and so counts as used");
                        // If we imported this variable from the global scope, any further use of
                        // the variable, including assignment, should count as "variable use" for
                        // the purposes of "unused variable" warnings.
                        return;
                }
                if (empty($varInfo->firstDeclared) && empty($varInfo->firstInitialized)) {
                        return;
                }
                if ($this->allowUnusedVariablesBeforeRequire && Helpers::isRequireInScopeAfter($phpcsFile, $varInfo, $scopeInfo)) {
                        return;
                }
                if ($scopeInfo->scopeStartIndex === 0 && $this->allowUnusedVariablesInFileScope) {
                        return;
                }
                if (
                        ! empty($varInfo->firstDeclared)
                        && $varInfo->scopeType === ScopeType::PARAM
                        && Helpers::isInAbstractClass(
                                $phpcsFile,
                                Helpers::getFunctionIndexForFunctionParameter($phpcsFile, $varInfo->firstDeclared) ?: 0
                        )
                        && Helpers::isFunctionBodyEmpty(
                                $phpcsFile,
                                Helpers::getFunctionIndexForFunctionParameter($phpcsFile, $varInfo->firstDeclared) ?: 0
                        )
                ) {
                        // Allow non-abstract methods inside an abstract class to have unused
                        // parameters if the method body does nothing. Such methods are
                        // effectively optional abstract methods so their unused parameters
                        // should be ignored as we do with abstract method parameters.
                        return;
                }

                $this->warnAboutUnusedVariable($phpcsFile, $varInfo);
        }

        /**
         * Register warnings for a variable that is defined but not used.
         *
         * @param File         $phpcsFile
         * @param VariableInfo $varInfo
         *
         * @return void
         */
        protected function warnAboutUnusedVariable(File $phpcsFile, VariableInfo $varInfo)
        {
                foreach (array_unique($varInfo->allAssignments) as $indexForWarning) {
                        Helpers::debug("variable '{$varInfo->name}' at end of scope looks unused");
                        $phpcsFile->addWarning(
                                'Unused %s %s.',
                                $indexForWarning,
                                'UnusedVariable',
                                [
                                        VariableInfo::$scopeTypeDescriptions[$varInfo->scopeType ?: ScopeType::LOCAL],
                                        "\${$varInfo->name}",
                                ]
                        );
                }
        }

        /**
         * @param File   $phpcsFile
         * @param string $varName
         * @param int    $stackPtr
         *
         * @return void
         */
        protected function warnAboutUndefinedVariable(File $phpcsFile, $varName, $stackPtr)
        {
                $phpcsFile->addWarning(
                        'Variable %s is undefined.',
                        $stackPtr,
                        'UndefinedVariable',
                        ["\${$varName}"]
                );
        }

        /**
         * @param File   $phpcsFile
         * @param string $varName
         * @param int    $stackPtr
         *
         * @return void
         */
        protected function warnAboutUndefinedArrayPushShortcut(File $phpcsFile, $varName, $stackPtr)
        {
                $phpcsFile->addWarning(
                        'Array variable %s is undefined.',
                        $stackPtr,
                        'UndefinedVariable',
                        ["\${$varName}"]
                );
        }

        /**
         * @param File   $phpcsFile
         * @param string $varName
         * @param int    $stackPtr
         *
         * @return void
         */
        protected function warnAboutUndefinedUnset(File $phpcsFile, $varName, $stackPtr)
        {
                $phpcsFile->addWarning(
                        'Variable %s inside unset call is undefined.',
                        $stackPtr,
                        'UndefinedUnsetVariable',
                        ["\${$varName}"]
                );
        }
}

sirbrillig / phpcs-variable-analysis / 24632078366

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous