Project stored-boolean narrowings through || truthy

`if (A || B)` truthy where `A` and `B` are booleans backed by stored
conditional-expression holders (e.g. `$isA = $obj instanceof ClassA;
$isB = $obj instanceof ClassB;`) needs to apply the held narrowings of
the *target* (`$obj`) to the OR-truthy scope as the union of the per-arm
narrowings. specifyTypesInCondition for each arm only sees the boolean
variable itself, so the `$obj` narrowing was invisible until a later
inner check pinned one of the booleans down.

For each conditional-holder target we now resolve its type in the
left-truthy and right-truthy filtered scopes, and when both narrow it
strictly below the original we add a sure type carrying the union to
the OR-truthy result.

Gated to keep certainty unchanged: only project when the target stays
Yes-defined in all three scopes — `if (empty($a['bar']))` for instance
must leave `$a` Maybe-defined because `empty()` tolerates undefined
offsets.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: ondrejmirtes

src/Analyser/MutatingScope.php

@@ -3348,6 +3348,14 @@ public function filterBySpecifiedTypes(SpecifiedTypes $specifiedTypes): self
 		);
 	}
 
+	/**
+	 * @return array<string, ConditionalExpressionHolder[]>
+	 */
+	public function getConditionalExpressions(): array
+	{
+		return $this->conditionalExpressions;
+	}
+
 	/**
 	 * @param ConditionalExpressionHolder[] $conditionalExpressionHolders
 	 */

src/Analyser/TypeSpecifier.php

@@ -82,6 +82,7 @@
 use PHPStan\Type\TypeTraverser;
 use PHPStan\Type\UnionType;
 use function array_key_exists;
+use function array_key_first;
 use function array_last;
 use function array_map;
 use function array_merge;
@@ -783,6 +784,7 @@ public function specifyTypesInCondition(
 					$types = $leftTypes->normalize($scope);
 				} else {
 					$types = $leftTypes->normalize($scope)->intersectWith($rightTypes->normalize($rightScope));
+					$types = $this->augmentBooleanOrTruthyWithConditionalHolders($scope, $rightScope, $expr, $types);
 				}
 			} else {
 				$types = $leftTypes->unionWith($rightTypes);
@@ -1941,6 +1943,81 @@ private function specifyTypesFromCallableCall(TypeSpecifierContext $context, Fun
 		return $this->specifyTypesFromAsserts($context, $call, $asserts, $parametersAcceptor, $scope);
 	}
 
+	/**
+	 * For `if ($a || $b)` truthy, expressions narrowed by stored conditional
+	 * holders (e.g. `$a = $obj instanceof ClassA;` records "when `$a` is
+	 * truthy, `$obj` is `ClassA`") need to be projected into the OR-truthy
+	 * scope as the union of the per-arm narrowings. specifyTypesInCondition
+	 * for each arm only looks at the boolean variable itself, so the held
+	 * narrowing of `$obj` would otherwise be invisible until a later check
+	 * pins one of the booleans down.
+	 *
+	 * For each conditional-holder target $T:
+	 * - resolve $T's type in the left-truthy and right-truthy filtered scopes
+	 * - if both narrow $T strictly below the original, add `$T : leftT|rightT`
+	 *   as a sure type to the OR-truthy result
+	 *
+	 * The asymmetric case (one arm narrows, the other doesn't) is intentionally
+	 * skipped: in the OR-truthy scope the arm that didn't narrow could still be
+	 * the truthy one, so the sound result is the original (unnarrowed) type.
+	 */
+	private function augmentBooleanOrTruthyWithConditionalHolders(MutatingScope $scope, MutatingScope $rightScope, BooleanOr|LogicalOr $expr, SpecifiedTypes $types): SpecifiedTypes
+	{
+		$leftTruthyScope = $scope->filterByTruthyValue($expr->left);
+		$rightTruthyScope = $rightScope->filterByTruthyValue($expr->right);
+
+		$seen = [];
+		foreach ([$scope, $rightScope] as $sourceScope) {
+			foreach ($sourceScope->getConditionalExpressions() as $exprString => $holders) {
+				if (isset($seen[$exprString])) {
+					continue;
+				}
+				if ($holders === []) {
+					continue;
+				}
+				$seen[$exprString] = true;
+				$targetExpr = $holders[array_key_first($holders)]->getTypeHolder()->getExpr();
+
+				// Only project when the target stays Yes-defined in the original
+				// scope and in both filtered branches. A sure type implicitly
+				// raises certainty to Yes, which would wrongly upgrade Maybe-defined
+				// variables — `if (empty($a['bar']))` for instance leaves `$a`
+				// Maybe-defined because `empty()` tolerates undefined offsets.
+				if (!$scope->hasExpressionType($targetExpr)->yes()) {
+					continue;
+				}
+				if (!$leftTruthyScope->hasExpressionType($targetExpr)->yes()) {
+					continue;
+				}
+				if (!$rightTruthyScope->hasExpressionType($targetExpr)->yes()) {
+					continue;
+				}
+
+				$origType = $scope->getType($targetExpr);
+				$leftType = $leftTruthyScope->getType($targetExpr);
+				$rightType = $rightTruthyScope->getType($targetExpr);
+
+				$leftNarrowed = !$leftType->equals($origType) && $origType->isSuperTypeOf($leftType)->yes();
+				$rightNarrowed = !$rightType->equals($origType) && $origType->isSuperTypeOf($rightType)->yes();
+
+				if (!$leftNarrowed || !$rightNarrowed) {
+					continue;
+				}
+
+				$unionType = TypeCombinator::union($leftType, $rightType);
+				if ($unionType->equals($origType)) {
+					continue;
+				}
+
+				$types = $types->unionWith(
+					$this->create($targetExpr, $unionType, TypeSpecifierContext::createTrue(), $scope),
+				);
+			}
+		}
+
+		return $types;
+	}
+
 	/**
 	 * @return array<string, ConditionalExpressionHolder[]>
 	 */

tests/PHPStan/Analyser/nsrt/bug-9519.php

@@ -0,0 +1,64 @@
+<?php
+
+namespace Bug9519;
+
+use function PHPStan\Testing\assertType;
+
+class ClassA {}
+class ClassB {}
+
+function instanceofVariants(mixed $obj): void
+{
+	$isA = $obj instanceof ClassA;
+	$isB = $obj instanceof ClassB;
+
+	if ($isA || $isB) {
+		assertType('Bug9519\\ClassA|Bug9519\\ClassB', $obj);
+	}
+
+	// Sanity check: the equivalent inline form has always worked, so the
+	// stored-boolean form should produce the same narrowing.
+	if (($obj instanceof ClassA) || ($obj instanceof ClassB)) {
+		assertType('Bug9519\\ClassA|Bug9519\\ClassB', $obj);
+	}
+}
+
+/**
+ * Three-way OR over stored booleans — every arm narrows the same target.
+ */
+class ClassC {}
+
+function threeWayInstanceof(mixed $obj): void
+{
+	$isA = $obj instanceof ClassA;
+	$isB = $obj instanceof ClassB;
+	$isC = $obj instanceof ClassC;
+
+	if ($isA || $isB || $isC) {
+		assertType('Bug9519\\ClassA|Bug9519\\ClassB|Bug9519\\ClassC', $obj);
+	}
+}
+
+/**
+ * Different narrowing kinds across the OR's arms — `null !==` on the left,
+ * `instanceof` on the right.
+ */
+function mixedNarrowingKinds(?ClassA $a, mixed $b): void
+{
+	$aNotNull = $a !== null;
+	$bIsB = $b instanceof ClassB;
+
+	if ($aNotNull || $bIsB) {
+		// Inside the truthy branch we don't know which arm fired, so each
+		// target keeps the union of (narrowed-when-its-arm-fired)
+		// and (original-when-the-other-arm-fired).
+		assertType(
+			'Bug9519\\ClassA|null',
+			$a,
+		);
+		assertType(
+			'mixed',
+			$b,
+		);
+	}
+}