Fix #757: Incorrect warning when using functions that return a reference

CLAUDE.md

@@ -306,6 +306,10 @@ PHPStan tracks whether expressions/statements have side effects ("impure points"
 
 Bugs occur when impure points are missed (e.g. inherited constructors of anonymous classes) or when `clearstatcache()` calls don't invalidate filesystem function return types.
 
+### FunctionCallParametersCheck: by-reference argument validation
+
+`FunctionCallParametersCheck` (`src/Rules/FunctionCallParametersCheck.php`) validates arguments passed to functions/methods. For by-reference parameters, it checks whether the argument is a valid lvalue (variable, array dim fetch, property fetch). It also allows function/method calls that return by reference (`&getString()`, `&staticGetString()`, `&refFunction()`), using `returnsByReference()` on the resolved reflection. The class is manually instantiated in ~20 test files, so adding a constructor parameter requires updating all of them. The `Scope` interface provides `getMethodReflection()` for method calls, while `ReflectionProvider` (injected into the class) is needed for resolving function reflections.
+
 ### Testing patterns
 
 - **Rule tests**: Extend `RuleTestCase`, implement `getRule()`, call `$this->analyse([__DIR__ . '/data/my-test.php'], [...expected errors...])`. Expected errors are `[message, line]` pairs. Test data files live in `tests/PHPStan/Rules/*/data/`.

src/Rules/FunctionCallParametersCheck.php

@@ -11,6 +11,7 @@
 use PHPStan\Reflection\ExtendedParameterReflection;
 use PHPStan\Reflection\ParameterReflection;
 use PHPStan\Reflection\ParametersAcceptor;
+use PHPStan\Reflection\ReflectionProvider;
 use PHPStan\Reflection\ResolvedFunctionVariant;
 use PHPStan\Rules\PhpDoc\UnresolvableTypeHelper;
 use PHPStan\Rules\Properties\PropertyReflectionFinder;
@@ -47,6 +48,7 @@ public function __construct(
 		private NullsafeCheck $nullsafeCheck,
 		private UnresolvableTypeHelper $unresolvableTypeHelper,
 		private PropertyReflectionFinder $propertyReflectionFinder,
+		private ReflectionProvider $reflectionProvider,
 		#[AutowiredParameter(ref: '%checkFunctionArgumentTypes%')]
 		private bool $checkArgumentTypes,
 		#[AutowiredParameter]
@@ -462,6 +464,10 @@ public function check(
 				continue;
 			}
 
+			if ($this->callReturnsByReference($argumentValue, $scope)) {
+				continue;
+			}
+
 			$errors[] = RuleErrorBuilder::message(sprintf(
 				$parameterPassedByReferenceMessage,
 				$this->describeParameter($parameter, $argumentName === null ? $i + 1 : null),
@@ -690,4 +696,46 @@ private function describeParameter(ParameterReflection $parameter, int|string|nu
 		return implode(' ', $parts);
 	}
 
+	private function callReturnsByReference(Expr $expr, Scope $scope): bool
+	{
+		if ($expr instanceof Node\Expr\MethodCall) {
+			if (!$expr->name instanceof Node\Identifier) {
+				return false;
+			}
+			$calledOnType = $scope->getType($expr->var);
+			$methodReflection = $scope->getMethodReflection($calledOnType, $expr->name->name);
+			if ($methodReflection === null) {
+				return false;
+			}
+			return $methodReflection->returnsByReference()->yes();
+		}
+
+		if ($expr instanceof Node\Expr\StaticCall) {
+			if (!$expr->name instanceof Node\Identifier) {
+				return false;
+			}
+			if ($expr->class instanceof Node\Name) {
+				$calledOnType = $scope->resolveTypeByName($expr->class);
+			} else {
+				$calledOnType = $scope->getType($expr->class);
+			}
+			$methodReflection = $scope->getMethodReflection($calledOnType, $expr->name->name);
+			if ($methodReflection === null) {
+				return false;
+			}
+			return $methodReflection->returnsByReference()->yes();
+		}
+
+		if ($expr instanceof Node\Expr\FuncCall) {
+			if ($expr->name instanceof Node\Name) {
+				if ($this->reflectionProvider->hasFunction($expr->name, $scope)) {
+					$functionReflection = $this->reflectionProvider->getFunction($expr->name, $scope);
+					return $functionReflection->returnsByReference()->yes();
+				}
+			}
+		}
+
+		return false;
+	}
+
 }

tests/PHPStan/Analyser/Bug9307CallMethodsRuleTest.php

@@ -24,7 +24,7 @@ protected function getRule(): Rule
 		$ruleLevelHelper = new RuleLevelHelper($reflectionProvider, true, false, true, true, false, false, true);
 		return new CallMethodsRule(
 			new MethodCallCheck($reflectionProvider, $ruleLevelHelper, true, true),
-			new FunctionCallParametersCheck($ruleLevelHelper, new NullsafeCheck(), new UnresolvableTypeHelper(), new PropertyReflectionFinder(), true, true, true, true),
+			new FunctionCallParametersCheck($ruleLevelHelper, new NullsafeCheck(), new UnresolvableTypeHelper(), new PropertyReflectionFinder(), $reflectionProvider, true, true, true, true),
 		);
 	}
 

tests/PHPStan/Rules/Classes/ClassAttributesRuleTest.php

@@ -37,6 +37,7 @@ protected function getRule(): Rule
 					new NullsafeCheck(),
 					new UnresolvableTypeHelper(),
 					new PropertyReflectionFinder(),
+					$reflectionProvider,
 					true,
 					true,
 					true,

tests/PHPStan/Rules/Classes/ClassConstantAttributesRuleTest.php

@@ -32,6 +32,7 @@ protected function getRule(): Rule
 					new NullsafeCheck(),
 					new UnresolvableTypeHelper(),
 					new PropertyReflectionFinder(),
+					$reflectionProvider,
 					true,
 					true,
 					true,

tests/PHPStan/Rules/Classes/ForbiddenNameCheckExtensionRuleTest.php

@@ -27,7 +27,7 @@ protected function getRule(): Rule
 		return new InstantiationRule(
 			$container,
 			$reflectionProvider,
-			new FunctionCallParametersCheck(new RuleLevelHelper($reflectionProvider, true, false, true, false, false, false, true), new NullsafeCheck(), new UnresolvableTypeHelper(), new PropertyReflectionFinder(), true, true, true, true),
+			new FunctionCallParametersCheck(new RuleLevelHelper($reflectionProvider, true, false, true, false, false, false, true), new NullsafeCheck(), new UnresolvableTypeHelper(), new PropertyReflectionFinder(), $reflectionProvider, true, true, true, true),
 			new ClassNameCheck(
 				new ClassCaseSensitivityCheck($reflectionProvider, true),
 				new ClassForbiddenNameCheck($container),

tests/PHPStan/Rules/Classes/InstantiationRuleTest.php

@@ -27,7 +27,7 @@ protected function getRule(): Rule
 		return new InstantiationRule(
 			$container,
 			$reflectionProvider,
-			new FunctionCallParametersCheck(new RuleLevelHelper($reflectionProvider, true, false, true, false, false, false, true), new NullsafeCheck(), new UnresolvableTypeHelper(), new PropertyReflectionFinder(), true, true, true, true),
+			new FunctionCallParametersCheck(new RuleLevelHelper($reflectionProvider, true, false, true, false, false, false, true), new NullsafeCheck(), new UnresolvableTypeHelper(), new PropertyReflectionFinder(), $reflectionProvider, true, true, true, true),
 			new ClassNameCheck(
 				new ClassCaseSensitivityCheck($reflectionProvider, true),
 				new ClassForbiddenNameCheck($container),

tests/PHPStan/Rules/Constants/ConstantAttributesRuleTest.php

@@ -38,6 +38,7 @@ protected function getRule(): Rule
 					new NullsafeCheck(),
 					new UnresolvableTypeHelper(),
 					new PropertyReflectionFinder(),
+					$reflectionProvider,
 					true,
 					true,
 					true,

tests/PHPStan/Rules/EnumCases/EnumCaseAttributesRuleTest.php

@@ -33,6 +33,7 @@ protected function getRule(): Rule
 					new NullsafeCheck(),
 					new UnresolvableTypeHelper(),
 					new PropertyReflectionFinder(),
+					$reflectionProvider,
 					true,
 					true,
 					true,

tests/PHPStan/Rules/Functions/ArrowFunctionAttributesRuleTest.php

@@ -32,6 +32,7 @@ protected function getRule(): Rule
 					new NullsafeCheck(),
 					new UnresolvableTypeHelper(),
 					new PropertyReflectionFinder(),
+					$reflectionProvider,
 					true,
 					true,
 					true,

tests/PHPStan/Rules/Functions/CallCallablesRuleTest.php

@@ -23,13 +23,15 @@ class CallCallablesRuleTest extends RuleTestCase
 
 	protected function getRule(): Rule
 	{
-		$ruleLevelHelper = new RuleLevelHelper(self::createReflectionProvider(), true, false, true, $this->checkExplicitMixed, false, false, true);
+		$reflectionProvider = self::createReflectionProvider();
+		$ruleLevelHelper = new RuleLevelHelper($reflectionProvider, true, false, true, $this->checkExplicitMixed, false, false, true);
 		return new CallCallablesRule(
 			new FunctionCallParametersCheck(
 				$ruleLevelHelper,
 				new NullsafeCheck(),
 				new UnresolvableTypeHelper(),
 				new PropertyReflectionFinder(),
+				$reflectionProvider,
 				true,
 				true,
 				true,

tests/PHPStan/Rules/Functions/CallToFunctionParametersRuleTest.php

@@ -30,7 +30,7 @@ protected function getRule(): Rule
 		$broker = self::createReflectionProvider();
 		return new CallToFunctionParametersRule(
 			$broker,
-			new FunctionCallParametersCheck(new RuleLevelHelper($broker, true, false, true, $this->checkExplicitMixed, $this->checkImplicitMixed, false, true), new NullsafeCheck(), new UnresolvableTypeHelper(), new PropertyReflectionFinder(), true, true, true, true),
+			new FunctionCallParametersCheck(new RuleLevelHelper($broker, true, false, true, $this->checkExplicitMixed, $this->checkImplicitMixed, false, true), new NullsafeCheck(), new UnresolvableTypeHelper(), new PropertyReflectionFinder(), $broker, true, true, true, true),
 		);
 	}
 
@@ -308,6 +308,25 @@ public function testPassingNonVariableToParameterPassedByReference(): void
 		]);
 	}
 
+	public function testBug757(): void
+	{
+		$this->analyse([__DIR__ . '/data/bug-757.php'], [
+			[
+				'Parameter #1 $s of function Bug757\useString is passed by reference, so it expects variables only.',
+				37,
+			],
+			[
+				'Parameter #1 $s of function Bug757\useString is passed by reference, so it expects variables only.',
+				40,
+			],
+		]);
+	}
+
+	public function testBug13711(): void
+	{
+		$this->analyse([__DIR__ . '/data/bug-13711.php'], []);
+	}
+
 	public function testImplodeOnPhp74(): void
 	{
 		$errors = [

tests/PHPStan/Rules/Functions/CallUserFuncRuleTest.php

@@ -20,7 +20,7 @@ class CallUserFuncRuleTest extends RuleTestCase
 	protected function getRule(): Rule
 	{
 		$reflectionProvider = self::createReflectionProvider();
-		return new CallUserFuncRule($reflectionProvider, new FunctionCallParametersCheck(new RuleLevelHelper($reflectionProvider, true, false, true, true, false, false, true), new NullsafeCheck(), new UnresolvableTypeHelper(), new PropertyReflectionFinder(), true, true, true, true));
+		return new CallUserFuncRule($reflectionProvider, new FunctionCallParametersCheck(new RuleLevelHelper($reflectionProvider, true, false, true, true, false, false, true), new NullsafeCheck(), new UnresolvableTypeHelper(), new PropertyReflectionFinder(), $reflectionProvider, true, true, true, true));
 	}
 
 	#[RequiresPhp('>= 8.0')]

tests/PHPStan/Rules/Functions/ClosureAttributesRuleTest.php

@@ -32,6 +32,7 @@ protected function getRule(): Rule
 					new NullsafeCheck(),
 					new UnresolvableTypeHelper(),
 					new PropertyReflectionFinder(),
+					$reflectionProvider,
 					true,
 					true,
 					true,

tests/PHPStan/Rules/Functions/FunctionAttributesRuleTest.php

@@ -32,6 +32,7 @@ protected function getRule(): Rule
 					new NullsafeCheck(),
 					new UnresolvableTypeHelper(),
 					new PropertyReflectionFinder(),
+					$reflectionProvider,
 					true,
 					true,
 					true,

tests/PHPStan/Rules/Functions/ParamAttributesRuleTest.php

@@ -32,6 +32,7 @@ protected function getRule(): Rule
 					new NullsafeCheck(),
 					new UnresolvableTypeHelper(),
 					new PropertyReflectionFinder(),
+					$reflectionProvider,
 					true,
 					true,
 					true,

tests/PHPStan/Rules/Functions/data/bug-13711.php

@@ -0,0 +1,20 @@
+<?php declare(strict_types = 1);
+
+namespace Bug13711;
+
+class Foo
+{
+	/** @var array<string> */
+	private array $array = [];
+
+	/** @return array<string> */
+	public function &getList(): array
+	{
+		return $this->array;
+	}
+
+	public function rewind(): void
+	{
+		reset($this->getList());
+	}
+}

tests/PHPStan/Rules/Functions/data/bug-757.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace Bug757;
+
+class A {
+	/** @var string */
+	public $foo = "bar";
+
+	public function &getString() : string {
+		return $this->foo;
+	}
+
+	public function getStringNoRef() : string {
+		return $this->foo;
+	}
+
+	public static function &staticGetString() : string {
+		static $s = "bar";
+		return $s;
+	}
+}
+
+function &refFunction() : string {
+	static $s = "bar";
+	return $s;
+}
+
+function noRefFunction() : string {
+	return "bar";
+}
+
+function useString(string &$s) : void {}
+
+function () {
+	$a = new A();
+	useString($a->getString()); // ok - returns by reference
+	useString($a->getStringNoRef()); // error - does not return by reference
+	useString(A::staticGetString()); // ok - returns by reference
+	useString(refFunction()); // ok - returns by reference
+	useString(noRefFunction()); // error - does not return by reference
+};

tests/PHPStan/Rules/Methods/CallMethodsRuleTest.php

@@ -35,7 +35,7 @@ protected function getRule(): Rule
 		$ruleLevelHelper = new RuleLevelHelper($reflectionProvider, $this->checkNullables, $this->checkThisOnly, $this->checkUnionTypes, $this->checkExplicitMixed, $this->checkImplicitMixed, false, true);
 		return new CallMethodsRule(
 			new MethodCallCheck($reflectionProvider, $ruleLevelHelper, true, true),
-			new FunctionCallParametersCheck($ruleLevelHelper, new NullsafeCheck(), new UnresolvableTypeHelper(), new PropertyReflectionFinder(), true, true, true, true),
+			new FunctionCallParametersCheck($ruleLevelHelper, new NullsafeCheck(), new UnresolvableTypeHelper(), new PropertyReflectionFinder(), $reflectionProvider, true, true, true, true),
 		);
 	}
 

tests/PHPStan/Rules/Methods/CallStaticMethodsRuleTest.php

@@ -53,6 +53,7 @@ protected function getRule(): Rule
 				new NullsafeCheck(),
 				new UnresolvableTypeHelper(),
 				new PropertyReflectionFinder(),
+				$reflectionProvider,
 				true,
 				true,
 				true,

tests/PHPStan/Rules/Methods/MethodAttributesRuleTest.php

@@ -32,6 +32,7 @@ protected function getRule(): Rule
 					new NullsafeCheck(),
 					new UnresolvableTypeHelper(),
 					new PropertyReflectionFinder(),
+					$reflectionProvider,
 					true,
 					true,
 					true,

tests/PHPStan/Rules/Properties/PropertyAttributesRuleTest.php

@@ -34,6 +34,7 @@ protected function getRule(): Rule
 					new NullsafeCheck(),
 					new UnresolvableTypeHelper(),
 					new PropertyReflectionFinder(),
+					$reflectionProvider,
 					true,
 					true,
 					true,

tests/PHPStan/Rules/Properties/PropertyHookAttributesRuleTest.php

@@ -32,6 +32,7 @@ protected function getRule(): Rule
 					new NullsafeCheck(),
 					new UnresolvableTypeHelper(),
 					new PropertyReflectionFinder(),
+					$reflectionProvider,
 					true,
 					true,
 					true,

tests/PHPStan/Rules/Traits/TraitAttributesRuleTest.php

@@ -39,6 +39,7 @@ protected function getRule(): Rule
 					new NullsafeCheck(),
 					new UnresolvableTypeHelper(),
 					new PropertyReflectionFinder(),
+					$reflectionProvider,
 					true,
 					true,
 					true,