Fix phpstan/phpstan#14227: Variable might not be defined false positive with unset in mutually exclusive branch

- Added preserveSafeConditionalExpressions() to MutatingScope to preserve conditional
  expressions through merges when one branch invalidates a variable (e.g. via unset())
  but the guard condition is disjoint from the other branch's types
- This also fixes related false positives for variables defined in different branches of
  if/elseif/else (bug-4173, dynamic-access test improvements)
- Restricted preservation to simple Variable expressions to avoid stale method call narrowing
- New regression test in tests/PHPStan/Rules/Variables/data/bug-14227.php

Author: phpstan-bot

src/Analyser/MutatingScope.php

@@ -3952,6 +3952,8 @@ public function mergeWith(?self $otherScope): self
 
 		$mergedExpressionTypes = $this->mergeVariableHolders($ourExpressionTypes, $theirExpressionTypes);
 		$conditionalExpressions = $this->intersectConditionalExpressions($otherScope->conditionalExpressions);
+		$conditionalExpressions = $this->preserveSafeConditionalExpressions($conditionalExpressions, $this->conditionalExpressions, $theirExpressionTypes);
+		$conditionalExpressions = $this->preserveSafeConditionalExpressions($conditionalExpressions, $otherScope->conditionalExpressions, $ourExpressionTypes);
 		$conditionalExpressions = $this->createConditionalExpressions(
 			$conditionalExpressions,
 			$ourExpressionTypes,
@@ -4051,6 +4053,75 @@ private function intersectConditionalExpressions(array $otherConditionalExpressi
 		return $newConditionalExpressions;
 	}
 
+	/**
+	 * Preserve conditional expressions from one scope that were dropped by
+	 * intersectConditionalExpressions because they don't exist in the other scope.
+	 *
+	 * This handles the case where a variable was invalidated (e.g. by unset()) in one
+	 * branch, causing its conditional expressions to be removed. When the guard condition
+	 * of a conditional expression is disjoint from the other scope's types for the guard
+	 * variable, the conditional expression is still valid and should be preserved.
+	 *
+	 * @param array<string, ConditionalExpressionHolder[]> $currentConditionalExpressions
+	 * @param array<string, ConditionalExpressionHolder[]> $scopeConditionalExpressions
+	 * @param array<string, ExpressionTypeHolder> $otherExpressionTypes
+	 * @return array<string, ConditionalExpressionHolder[]>
+	 */
+	private function preserveSafeConditionalExpressions(
+		array $currentConditionalExpressions,
+		array $scopeConditionalExpressions,
+		array $otherExpressionTypes,
+	): array
+	{
+		foreach ($scopeConditionalExpressions as $exprString => $holders) {
+			if (array_key_exists($exprString, $currentConditionalExpressions)) {
+				continue;
+			}
+
+			if (array_key_exists($exprString, $otherExpressionTypes)) {
+				continue;
+			}
+
+			if (count($holders) === 0) {
+				continue;
+			}
+
+			$firstHolder = $holders[array_key_first($holders)];
+			$subjectExpr = $firstHolder->getTypeHolder()->getExpr();
+			if (!$subjectExpr instanceof Variable || !is_string($subjectExpr->name)) {
+				continue;
+			}
+
+			$safeHolders = [];
+			foreach ($holders as $key => $holder) {
+				$safe = true;
+				foreach ($holder->getConditionExpressionTypeHolders() as $guardExprString => $guardHolder) {
+					if (!array_key_exists($guardExprString, $otherExpressionTypes)) {
+						$safe = false;
+						break;
+					}
+					if (!$otherExpressionTypes[$guardExprString]->getType()->isSuperTypeOf($guardHolder->getType())->no()) {
+						$safe = false;
+						break;
+					}
+				}
+				if (!$safe) {
+					continue;
+				}
+
+				$safeHolders[$key] = $holder;
+			}
+
+			if (count($safeHolders) <= 0) {
+				continue;
+			}
+
+			$currentConditionalExpressions[$exprString] = $safeHolders;
+		}
+
+		return $currentConditionalExpressions;
+	}
+
 	/**
 	 * @param array<string, ConditionalExpressionHolder[]> $newConditionalExpressions
 	 * @param array<string, ConditionalExpressionHolder[]> $existingConditionalExpressions

tests/PHPStan/Rules/Variables/DefinedVariableRuleTest.php

@@ -911,12 +911,7 @@ public function testBug4173(): void
 		$this->polluteScopeWithLoopInitialAssignments = false;
 		$this->checkMaybeUndefinedVariables = true;
 		$this->polluteScopeWithAlwaysIterableForeach = true;
-		$this->analyse([__DIR__ . '/data/bug-4173.php'], [
-			[
-				'Variable $value might not be defined.', // could be fixed
-				30,
-			],
-		]);
+		$this->analyse([__DIR__ . '/data/bug-4173.php'], []);
 	}
 
 	public function testBug5805(): void
@@ -1119,29 +1114,13 @@ public function testDynamicAccess(): void
 				18,
 			],
 			[
-				'Variable $foo might not be defined.',
-				36,
-			],
-			[
-				'Variable $foo might not be defined.',
-				37,
-			],
-			[
-				'Variable $bar might not be defined.',
+				'Undefined variable: $bar',
 				38,
 			],
 			[
-				'Variable $bar might not be defined.',
-				40,
-			],
-			[
-				'Variable $foo might not be defined.',
+				'Undefined variable: $foo',
 				41,
 			],
-			[
-				'Variable $bar might not be defined.',
-				42,
-			],
 			[
 				'Undefined variable: $buz',
 				44,
@@ -1400,4 +1379,19 @@ public function testBug14117(): void
 		]);
 	}
 
+	public function testBug14227(): void
+	{
+		$this->cliArgumentsVariablesRegistered = true;
+		$this->polluteScopeWithLoopInitialAssignments = false;
+		$this->checkMaybeUndefinedVariables = true;
+		$this->polluteScopeWithAlwaysIterableForeach = true;
+
+		$this->analyse([__DIR__ . '/data/bug-14227.php'], [
+			[
+				'Variable $value might not be defined.',
+				33,
+			],
+		]);
+	}
+
 }

tests/PHPStan/Rules/Variables/data/bug-14227.php

@@ -0,0 +1,35 @@
+<?php declare(strict_types = 1);
+
+namespace Bug14227;
+
+function foo(): void {
+	$key = rand(0, 2);
+
+	if ($key === 1) {
+		$value = 'test';
+	}
+
+	if ($key === 2) {
+		unset($value);
+	}
+
+	if ($key === 1) {
+		echo $value; // should not report "might not defined"
+	}
+}
+
+function bar(): void {
+	$key = rand(0, 2);
+
+	if ($key === 1) {
+		$value = 'test';
+	}
+
+	if ($key !== 0) {
+		unset($value);
+	}
+
+	if ($key === 1) {
+		echo $value; // SHOULD report - unset also runs when $key === 1
+	}
+}