array_walk with pass-by-reference causes false positive unused variable

[sirbrillig]

This code produces Unused variable $value, when it is in fact used:

     array_walk($userNameParts, static function (string &$value): void {
            if (strlen($value) <= 3) {
                return;
            }

            $value = ucfirst($value);
        });

Reported by @Levivb in #214

[sirbrillig]

This is supposed to be handled by the code here:

phpcs-variable-analysis/VariableAnalysis/Sniffs/CodeAnalysis/VariableAnalysisSniff.php

Lines 1675 to 1680 in 29b6bb4

	if ($varInfo->referencedVariableScope !== null && isset($varInfo->firstInitialized)) {
	// 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;

but in this case, referencedVariableScope is null for some reason, which implies that this block is not firing:

phpcs-variable-analysis/VariableAnalysis/Sniffs/CodeAnalysis/VariableAnalysisSniff.php

Lines 620 to 625 in 29b6bb4

	// 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)) {
	$varInfo = $this->getOrCreateVariableInfo($varName, $functionPtr);
	$varInfo->referencedVariableScope = $outerScope;
	}

[sirbrillig]

Actually, it looks like the variable is correctly being marked as pass-by-reference, but then when it reaches where the variable is used the code thinks that the variable is a new instance; more specifically, that it has a new scope. The original variable is defined as having a scope starting with the array_walk closure, but the new variable's scope starts at the enclosing function.

The bug is happening because the scope detection code is getting confused about the difference between a bound reference variable and one which is going to be bound at runtime.

For example:

$foo = 'hello';
$bar = &$foo; // $bar is now a reference variable bound to $foo
$bar = 'bye'; // this writes to the bound variable; now $foo is 'bye'

array_walk($data, function (&$foo) { // $foo is now a reference variable that will be bound at runtime
  $foo = ucfirst($foo); // this writes to the bound variable, but we can't know anything about that variable since it does not exist in the code before runtime
});