Skip to content

Compare branches of two conditional types in isSuperTypeOf() only when they share the same condition, and include negation in equals() - #7097

Merged
staabm merged 2 commits into
phpstan:2.3.xfrom
phpstan-bot:create-pull-request/patch-hp4zn2s
Nov 17, 2026
Merged

staabm merged 2 commits into
phpstan:2.3.xfrom
phpstan-bot:create-pull-request/patch-hp4zn2s

Conversation

@phpstan-bot

Copy link
Copy Markdown
Collaborator

Summary

A return type that intersects two conditional types, such as
($p is '' ? decimal-int-string : string) & ($p is lowercase-string ? lowercase-string : string),
lost lowercase-string. The intersection was collapsed into the first conditional when the PHPDoc was resolved. This happened because ConditionalType*::isSuperTypeOf() compared only the if/else branches of two conditionals and ignored what each one was conditioned on.

Changes

  • src/Type/ConditionalType.php: isSuperTypeOf() compares branches only when negated, subject and target are equal. Otherwise it falls back to isSuperTypeOfDefault(). equals() now also compares negated.
  • src/Type/ConditionalTypeForParameter.php: the same change, using parameterName in place of subject.
  • turbo-ext/src/ConditionalType.cpp, turbo-ext/src/ConditionalTypeForParameter.cpp: the C++ mirrors use a new hasSameCondition() helper, shared by isSuperTypeOf() and equals(). Reads happen in the same order as the PHP twin.
  • turbo-ext/tests/type-family.php: added differential cases for conditionals whose subject, target or parameter name differ.

Analogous cases found and fixed by the same change:

  • Union of conditionals: TypeCombinator::union() also relies on isSuperTypeOf(). As a result, ($p is '' ? decimal-int-string : string) | ($p is lowercase-string ? lowercase-string : string) gave lowercase-string for 'foo-' (the correct result is string).
  • is vs is not: ($p is int ? int : string) | ($p is not int ? int : string) collapsed to a single conditional, giving string / int instead of int|string.
  • Template-subject ConditionalType (T is '' ? ... : ...), which is the ConditionalType sibling of ConditionalTypeForParameter, showed the same symptom as the issue.
  • equals() ignored negation in both classes.

Root cause

isSuperTypeOf() on two conditionals checked if ⊇ if' and else ⊇ else'. That is only sound when both conditionals choose a branch from the same condition. With different conditions, the branches that end up selected are unrelated. TypeCombinator then treated one conditional as absorbing the other in intersections and unions. Requiring the same negation, subject or parameter name, and target keeps the precise answer for identical conditions and uses the sound late-resolvable default otherwise.

Test

  • tests/PHPStan/Analyser/nsrt/bug-15759.php:

    • the issue's three functions, verbatim;
    • a union of conditionals;
    • an is / is not union;
    • a template-subject (ConditionalType) intersection.

    Without the fix, the test fails on 7 assertions.

  • turbo-ext/tests/type-family.php: new "cond pairs" observations. Without the PHP change these differ from the native results.

  • make tests passes, both without the extension (apart from a missing // lint >= 8.0 header on the new test, now added) and with the turbo extension loaded. make phpstan passes. The turbo smoke, side-by-side and signature-parity checks pass.

Fixes phpstan/phpstan#15759

…hen they share the same condition, and include negation in `equals()`

- ConditionalType::isSuperTypeOf() and ConditionalTypeForParameter::isSuperTypeOf()
  compared the if/else branches of any two conditionals, ignoring subject /
  parameter name, target and negation. `($p is lowercase-string ? lowercase-string : string)`
  was therefore considered a supertype of `($p is '' ? decimal-int-string : string)`
  (decimal-int-string is lowercase), and TypeCombinator::intersect() dropped it.
  The branch comparison now only happens when the negation, the subject (or
  parameter name) and the target are equal; otherwise the late-resolvable
  default is used.
- The same mistake made TypeCombinator::union() collapse conditionals with
  different conditions (wrong union results, and `is` vs `is not` conditionals
  absorbing each other).
- ConditionalType::equals() and ConditionalTypeForParameter::equals() ignored
  `negated`, so `($p is int ? A : B)` equalled `($p is not int ? A : B)`.
- Ported both changes to the turbo-ext C++ mirrors (ConditionalType.cpp,
  ConditionalTypeForParameter.cpp) via a shared hasSameCondition() helper, and
  extended the type-family differential coverage.

@VincentLanglet VincentLanglet left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Explain why the bug was specific to the exemple with decimal-int-string and numeric-string was already working fine

@phpstan-bot

Copy link
Copy Markdown
Collaborator Author

The bug wasn't really about decimal-int-string. That type was just the one case where a type relationship that happens to be true made the faulty comparison fire. I made no code changes for this review, so there are no new commits and I didn't run make tests or make phpstan again.

The comparison before the fix. Take the two conditionals from the issue:

  • A = $p is '' ? X : string
  • B = $p is lowercase-string ? lowercase-string : string

When the PHPDoc is resolved, TypeCombinator::intersect(A, B) asks each conditional whether it is a supertype of the other. If one says yes, it keeps the narrower conditional and drops the other. The old ConditionalTypeForParameter::isSuperTypeOf() only compared the branches and ignored the conditions. So B->isSuperTypeOf(A) was computed as:

lowercase-string ⊇ X   AND   string ⊇ string

The else branches always give "yes". The result therefore depends only on whether lowercase-string ⊇ X. I checked this for each type in the issue against the current code:

X lowercase-string->isSuperTypeOf(X) Result
decimal-int-string Yes (only digits and an optional -, so always lowercase) B ⊇ A is Yes, so B is dropped and lowercase-string is lost
numeric-string Maybe (can contain E, e.g. '1E5') Maybe, both kept
non-decimal-int-string Maybe (can contain uppercase, e.g. '1E5', 'ABC') Maybe, both kept

Why the "yes" was wrong. A takes its if-branch when $p is '', and B takes its if-branch when $p is a lowercase string. These are different conditions, so the branches chosen for a given argument don't line up. For 'foo-', A gives string and B gives lowercase-string. Comparing the two if-branches says nothing about how A and B relate.

Why numeric-string seemed to work. It wasn't handled correctly either: the comparison was still unsound, but it returned "maybe", so neither conditional was dropped. Any if-branch that is always lowercase would have hit the bug, for example '1', 'abc', '' or int-string, not just decimal-int-string.

What the fix changes. Branches are now compared only when both conditionals have the same parameter or subject, target and negation. In every other case the code falls back to the late-resolvable default. The union and is / is not cases in the test file come from the same root cause.

public function equals(Type $type): bool
{
return $type instanceof self
&& $this->negated === $type->negated

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this change is not covered by a test

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added the missing test coverage in one commit, 518de62ab, and changed no source code. make tests, make phpstan and make cs all pass. Nothing is pushed.

"Not covered by a test" (the negated check in equals() of both classes, and the negated and parameterName checks in ConditionalTypeForParameter::isSuperTypeOf()):

I added two unit tests, tests/PHPStan/Type/ConditionalTypeTest.php and tests/PHPStan/Type/ConditionalTypeForParameterTest.php. Each one checks:

  • isSuperTypeOf(): returns "yes" for the same condition, including when the other type's branches are narrower. Returns "maybe" when only the negation, the subject (or parameter name, e.g. $x vs $y), or the target differs.
  • equals(): returns true for identical conditionals, and false when exactly one of these differs: negation, subject or parameter name, target, if, else. Both directions are checked.

With the old versions of the two PHP classes swapped back in, 8 of these cases fail: each new condition in isSuperTypeOf() and the negated check in both equals() methods. All 22 pass with the fix.

"Do we really support intersections of conditional types in phpdoc?"

Yes, they already worked before this PR; the only problem was the wrong collapse it fixes. phpdoc-parser reads (A) & (B) with parenthesised conditionals as an intersection node. TypeNodeResolver::resolveIntersectionTypeNode() (src/PhpDoc/TypeNodeResolver.php:701) combines the parts with TypeCombinator::intersect(), and each conditional is resolved against the argument at the call site.

I checked this by analysing a standalone file with bin/phpstan:

Argument Result
'foo-' lowercase-string
'' decimal-int-string
'FOO' string
an unknown string string

The WordPress wp_unique_id() return type in the issue uses exactly this form. I found no existing test with an intersection of conditional types, so bug-15759.php is the first one.

Comment on lines +10 to +13
* @return (
* ( $p is '' ? decimal-int-string : string )
* & ( $p is lowercase-string ? lowercase-string : string )
* )

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

do we really support intersections of conditional types in phpdoc?

public function equals(Type $type): bool
{
return $type instanceof self
&& $this->negated === $type->negated

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this change is not covered by a test

if (
$type instanceof self
&& $this->negated === $type->negated
&& $this->parameterName === $type->parameterName

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this line is not covered by a test

… conditions

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@staabm
staabm merged commit b91615f into phpstan:2.3.x Nov 17, 2026
907 of 909 checks passed
@staabm
staabm deleted the create-pull-request/patch-hp4zn2s branch November 17, 2026 14:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Conditional return type loses lowercase-string when intersected with a conditional that has a decimal-int-string branch

3 participants