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

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?

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.

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.

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.