Resolve conditional @throws types like ($x is 0 ? Exception : void) at call sites and throw points

[phpstan-bot]

Summary

PHPStan already supports conditional return types such as ($x is 0 ? never : float), but conditional @throws types were not supported: a @throws ($x is 0 ? Exception : void) declaration was rejected by InvalidThrowsPhpDocValueRule as "not subtype of Throwable", the function body was wrongly reported as missing the exception in its @throws, and callers never benefited from the per-argument precision.

This change makes conditional @throws types first-class:

• The declaration is accepted when every branch is a valid throws type.
• A caller that triggers the throwing branch (e.g. inverse(0)) is reported as missing the exception in its own @throws, while a caller that does not (e.g. inverse(7), or inverse($x) with $x of type int<3, 5>) is not.
• The function body itself is matched against its conditional @throws, using the parameter narrowing at each throw point.

Changes

• src/Analyser/ConditionalThrowTypeResolver.php (new): resolves ConditionalTypeForParameter inside a throws type.
  • resolveForCall() builds the parameter→argument-type map from a call's arguments (named, positional, variadic and default values) and converts the conditional via toConditional(), then resolves late-resolvable types.
  • resolveForScope() resolves the conditional against the parameter variables narrowed in a given scope (used inside the function body).
• src/Analyser/ExprHandler/FuncCallHandler.php, src/Analyser/ExprHandler/Helper/MethodThrowPointHelper.php, src/Analyser/ExprHandler/NewHandler.php: resolve the reflection's throws type with resolveForCall() before turning it into a throw point, so function calls, method calls, static-method calls and new all honour conditional throws.
• src/Rules/Exceptions/MissingCheckedExceptionInThrowsCheck.php: resolve the declared throws type per throw point with resolveForScope() (this check backs the function, method and property-hook missing-throws rules).
• src/Rules/PhpDoc/InvalidThrowsPhpDocValueRule.php: recurse into ConditionalType/ConditionalTypeForParameter branches; void is accepted only standalone or inside a conditional branch (so Throwable|void stays invalid).

All resolution paths short-circuit on !$throwType->hasTemplateOrLateResolvableType(), so ordinary throws types are unaffected.

Root cause

A conditional @throws type is resolved into the same ConditionalTypeForParameter representation as a conditional return type, but nothing ever resolved it: throws types live on the function/method reflection and are read raw (getThrowType()), bypassing the call-site ResolvedFunctionVariant machinery that resolves conditional return types. As a result the conditional always collapsed to the Maybe-certain union of its branches (Exception|void), which is neither a clean Throwable (validation failure) nor a precise per-call result (no caller precision, false "missing" on the body).

The fix mirrors the conditional-return-type resolution for throws: at every place the raw throws type is consumed, the ConditionalTypeForParameter is resolved against the relevant subject — the call arguments at call sites, the narrowed parameter variables at throw points.

Test

• tests/PHPStan/Rules/PhpDoc/InvalidThrowsPhpDocValueRuleTest: added valid conditional throws (($x is 0 ? Exception : void), ($x is 0 ? Exception : RuntimeException)) which produce no error, and an invalid-branch case (($x is 0 ? stdClass : void)) which is still reported.
• tests/PHPStan/Rules/Exceptions/MissingCheckedExceptionInFunctionThrowsRuleTest::testConditionalThrows: a conditional-throwing inverse() function and callers — inverse(0) and inverse($x:int) are reported as missing the exception, while inverse(7) and inverse($x:int<3,5>) are not, and the body of inverse() itself is clean.
• tests/PHPStan/Rules/Exceptions/MissingCheckedExceptionInMethodThrowsRuleTest::testConditionalThrows: the same behaviour for instance method calls, static method calls and constructor (new) calls (the analogous parallel constructs).

Fixes phpstan/phpstan#7906
Fixes phpstan/phpstan#9497

[ondrejmirtes]

Is it correctly remapped when a parameter name changes during PHPDoc inheritance?

[VincentLanglet]

There is ConditionalTypeForParameter and ConditionalType with appropriate PhpDocParser Node

Wouldn't it better to introduce a

PHPStan\PhpDocParser\Ast\Type\ConditionalTypeForThrowsNode

[phpstan-bot]

I've now fully traced the flow and can address the review accurately. The reviewer's suggestion concerns the PhpDocParser AST layer, which lives in a separate package — let me lay out the analysis rather than fabricate a cross-repo change.

Response to the review

Thanks @VincentLanglet — I looked into whether a dedicated PHPStan\PhpDocParser\Ast\Type\ConditionalTypeForThrowsNode is the right layer for this, and there's a structural constraint worth flagging before going that route.

The phpdoc type parser is context-free. @throws is parsed by parseThrowsTagValue(), which just delegates to the generic typeParser->parse():

private function parseThrowsTagValue(TokenIterator $tokens): Ast\PhpDoc\ThrowsTagValueNode
{
    $type = $this->typeParser->parse($tokens);
    ...
}

So ($x is 0 ? Exception : void) produces the exact same ConditionalTypeForParameterNode whether it appears in @return, @param, or @throws — the parser has no idea which tag it's inside. To emit a ConditionalTypeForThrowsNode, phpstan/phpdoc-parser (a separate repo/package) would have to become throws-aware, either by special-casing the throws tag during parsing or by post-rewriting the node. That can't be done from phpstan-src — it can only consume node types the parser already ships.

What we'd gain vs. duplicate. The only genuinely throws-specific wrinkle today is that void is a legal branch (meaning "does not throw"), which is why InvalidThrowsPhpDocValueRule allows void only inside conditional branches. Everything else — toConditional(), late-resolvable resolution, TypeTraverser mapping in ConditionalThrowTypeResolver — is identical to how conditional return types already resolve and is verified correct. A dedicated node would fork that resolution path to get one void-handling distinction, while reusing ConditionalTypeForParameter keeps a single, shared, already-tested resolution path.

My recommendation: keep the ConditionalTypeForParameter representation at the Type level (the resolution semantics are genuinely the same as conditional return types), and contain the only throws-specific rule — void acceptance — where it already lives. If you'd prefer the AST-level distinction regardless, I'm glad to open a phpstan/phpdoc-parser PR adding ConditionalTypeForThrowsNode and the throws-aware parsing, then wire TypeNodeResolver/resolveThrowsTags through it here — but since it's a cross-repo change that forks the shared resolution, I wanted to confirm that's the direction you want before doing it.

Separately, on @ondrejmirtes's earlier question about parameter-name remapping during PHPDoc inheritance — that's a real concern with the current getParameterName()-keyed matching and is worth a dedicated test/fix; I'll address it as its own change since it's orthogonal to the node-type question.

---

I did not make code changes or commits for this review point, because the requested change (ConditionalTypeForThrowsNode) belongs in the separate phpstan/phpdoc-parser package and cannot be implemented from within phpstan-src — the type parser there is context-free and would need throws-awareness first. Pushing an empty or fabricated commit here would misrepresent that.

Two things I can act on next if you confirm:

1. Cross-repo route: open a phpstan/phpdoc-parser PR for the dedicated node and wire it through here.
2. Inheritance remapping: investigate and fix the parameter-name remapping concern raised by @ondrejmirtes (a concrete, phpstan-src-local change with its own test).

Want me to proceed with (1), (2), or both?

[VincentLanglet]

I think this should support ConditionalType too since the method could have a phpdoc like

@template TKey of int|string
@throws (TKey is int ? void : Exception)

[phpstan-bot]

I've addressed the review. Here's a summary of what I did.

Review point

VincentLanglet asked that the resolver also support ConditionalType (template-based conditional throws), e.g.:

@template TKey of int|string
@throws (TKey is int ? void : Exception)

This was a real gap: the resolver only handled ConditionalTypeForParameter (subject is a $param). A conditional whose subject is a template type parses into a ConditionalType, which was never resolved against the inferred template type map — so callers got no precision and the function body got a false "missing @throws".

Changes

src/Analyser/ConditionalThrowTypeResolver.php

• resolveForCall() now, after the existing ConditionalTypeForParameter resolution, also resolves template types via the call-site resolvedTemplateTypeMap / callSiteVarianceMap (the same machinery ResolvedFunctionVariant uses for conditional return types) when the parameters acceptor is an ExtendedParametersAcceptor. So lookup(1) resolves to the void branch (no throw) while lookup('foo') resolves to the Exception branch (throws).
• resolveForScope() now collapses an unresolvable template conditional to the union of its branches (resolveUnresolvableTypes: true) rather than leaving it as a Maybe-certain conditional. Inside the body the template isn't bound to a concrete type, and the previous Maybe made isSuperTypeOf(...).yes() fail, producing a false positive on the function's own throw point.

InvalidThrowsPhpDocValueRule already recurses into ConditionalType branches, so validation needed no change — it accepts the valid template conditional and still rejects an invalid branch like (TKey is int ? void : stdClass).

Tests

• Function, method, static-method and constructor call sites with a template-based conditional throws (lookupInt → no error, lookupString/lookupUnknown → reported), plus a clean generic body.
• Validation: a valid template conditional throws and an invalid-branch one ((TKey of int|string is int ? void : stdClass) reported).

make tests (exceptions + phpdoc suites) and make phpstan both pass. Committed and pushed.

One note I'll flag honestly: ondrejmirtes's earlier question about parameter-name remapping during PHPDoc inheritance is still orthogonal and not addressed here — happy to take that as a separate change if you'd like.

[VincentLanglet]

Add test with nested conditional types

[phpstan-bot]

I've addressed VincentLanglet's review request to add tests with nested conditional types. Here's a summary.

Review request

Add test with nested conditional types

A "nested" conditional throws type is one where a branch is itself a conditional, e.g. ($x is 0 ? Exception : ($y is 0 ? Exception : void)).

What I added

1. Validation (InvalidThrowsPhpDocValueRule) — tests/.../PhpDoc/data/incompatible-throws.php:

• nestedConditionalThrows — a valid nested conditional (all branches are Throwable subtypes or void) → no error.
• nestedConditionalThrowsInvalidBranch — an invalid stdClass buried two levels deep in the nested else→else branch → reported as ($x is int ? Exception : ($y is int ? stdClass : void)) is not subtype of Throwable (line 177).

2. Call-site resolution (ConditionalThrowTypeResolver) — tests/.../Exceptions/data/conditional-throws-function.php:

• nestedInverse(int $x, int $y) with a nested conditional throws, plus three callers:
  • nestedInverse(0, 5) → resolves to the outer Exception branch → caller flagged as missing @throws.
  • nestedInverse(3, 0) → resolves through the outer else into the nested Exception branch → caller flagged.
  • nestedInverse(3, 5) → resolves to the nested void branch (no throw) → caller clean.
  • The nestedInverse() body itself is clean (no false positive).

Verification of meaningfulness

Per the project's testing discipline, I confirmed the nested validation test isn't a no-op: I temporarily stopped isThrowsValid() from recursing into a nested ConditionalTypeForParameter else-branch and watched the line-177 case stop being reported, then restored the implementation. This proves the new test specifically exercises the recursive descent more than one level deep (the existing flat-conditional tests only cover a single level).

Results

• InvalidThrowsPhpDocValueRuleTest — 7/7 pass
• MissingCheckedExceptionInFunctionThrowsRuleTest — 2/2 pass
• Full Exceptions/ + throws PhpDoc suites — 125 pass (2 skipped, PHP-version-gated)
• make phpstan — no errors

Committed as be0980f4d and pushed. The change is test-only — no production code changes were needed, since the existing recursion in isThrowsValid() and the TypeTraverser-based mapping in ConditionalThrowTypeResolver already handle nesting correctly; these tests lock that behavior in.

[staabm]

add regression tests for snippets mentioned in phpstan/phpstan#9497 (comment)

[phpstan-bot]

Done. Here's a summary of how I addressed staabm's review.

Review request

add regression tests for snippets mentioned in phpstan/phpstan#9497 (comment 4125494496)

That comment links two playground reproductions. I fetched both — they're generic (template-based) @throws T cases, not conditional ones:

1. @throws T with @param T $e — throwIt(RuntimeException $e), T of RuntimeException, called as $this->throwIt(new RangeException).
2. @throws T with @param class-string<T> $e — throwIt(string $e) doing throw new $e, called as $this->throwIt(RangeException::class).

In both, the caller sayHello() declares @throws RangeException. Since T is bound to RangeException at the call site, the call-site resolution this PR adds must resolve @throws T → RangeException, so no missing-throws error should be reported.

What I added

• tests/PHPStan/Rules/Exceptions/data/generic-throws-9497.php — both snippets (verbatim from the playground, namespaced as GenericThrows9497).
• MissingCheckedExceptionInMethodThrowsRuleTest::testGenericThrows() — asserts zero errors.

Verification it's meaningful

I temporarily disabled ConditionalThrowTypeResolver::resolveForCall() in MethodThrowPointHelper and confirmed the test fails with:

Method GenericThrows9497\Test::sayHello() throws checked exception T of RuntimeException ...
Method GenericThrows9497\TestClassString::sayHello() throws checked exception T of RuntimeException ...

i.e. without the PR's resolution the unbound T of RuntimeException leaks as the throw type. Restored the code and the test passes.

Results

• MissingCheckedExceptionInMethodThrowsRuleTest — 5/5 pass.
• Full Rules/Exceptions/ + InvalidThrowsPhpDocValueRuleTest — 126 pass (2 skipped, version-gated).
• make phpstan — no errors.

Committed as 0c87f6a66 and pushed. The change is test-only — the existing template-throws resolution already handles these; the tests lock the issue #9497 behavior in.

[ondrejmirtes]

My only problem with the code is that there's nothing specific about @throws in ConditionalThrowTypeResolver, so the class could be renamed and used for more scenarios, like resolving conditional types in PHPDoc tags like @phpstan-assert, @phpstan-self-out, and @param-out. Right now I suspect there must be duplicated logic because these tags need the same logic that's added here in ConditionalThrowTypeResolver.

[VincentLanglet]

ConditionalThrowTypeResolver have nothing explicitly related to @throws tag.

Is there some duplicated logic worth to be reused for either

• other conditional types
• @phpstan-assert, @phpstan-self-out, and/or @param-out

[phpstan-bot]

Pushed. Here's how I addressed the review.

Review point

ConditionalThrowTypeResolver has nothing explicitly related to @throws. Is there some duplicated logic worth reusing for other conditional types / @phpstan-assert, @phpstan-self-out, @param-out?

Yes on both counts. Three commits:

1. Rename ConditionalThrowTypeResolver to ConditionalTypeResolver (b313685)

Nothing in it was throws-specific. The class doc now states what it actually is: resolution for conditional types declared in tags that live on the function/method reflection rather than on the ParametersAcceptor — and why the other tags don't need it (see below).

2. Share the ConditionalTypeForParameter resolution in one place (5046108)

There were three copies of the same traversal turning every ConditionalTypeForParameter into a ConditionalType on its parameter's subject, each including the traverse-children-first dance that avoids an infinite loop on a colliding parameter name:

• ResolvedFunctionVariantWithOriginal::resolveConditionalTypesForParameter() — @return, @param, @param-out, @param-closure-this
• TypeSpecifier — @phpstan-assert
• ConditionalTypeResolver — @throws

Now ConditionalTypeForParameter::resolveInType() does it once, taking a callback that maps a parameter name to its subject type; each caller only describes where its subjects come from (bound arguments, argument expressions, scope variables). This also let collectParameterNames() go — the scope path resolves lazily like the others.

3. Resolve conditional @phpstan-self-out types at the call site (80e49dc)

Checking the tags you listed found one real gap. @param-out and @phpstan-assert were already fine — selectFromArgs() covers out-types, and TypeSpecifier resolves asserts itself. But @phpstan-self-out lives on the method reflection like @throws, and MethodCallHandler only substituted template types, so a conditional self-out collapsed to the union of its branches:

/** @phpstan-self-out ($size is 0 ? EmptyCollection : NonEmptyCollection) */
public function setSize(int $size): void;

$c->setSize(0);  // before: EmptyCollection|NonEmptyCollection   after: EmptyCollection
$c->setSize(7);  // before: EmptyCollection|NonEmptyCollection   after: NonEmptyCollection

Routing it through the renamed resolver surfaced one thing worth flagging: resolveForCall() always re-resolved the variant from the argument types, which loses a closure argument's inferred return type. That broke nsrt/bug-13253.php (Pfline::map()'s self-out). Fixed by taking the acceptor as is when it's already bound to the call's arguments (new ResolvedFunctionVariant::hasBoundArgs()), and only rebuilding otherwise — which is the @throws case, where the acceptor is either structural or resolved against class generics only.

Verification

• New tests/PHPStan/Analyser/nsrt/conditional-self-out.php covers the parameter-subject and template-subject forms plus the unresolvable case. Confirmed it fails without the MethodCallHandler change (lines 51/54 report the unresolved union) and passes with it.
• make tests: 21499 passing, 95 skipped (version-gated).
• make phpstan: no errors. make cs: clean.