[phpstan-bot]

Summary

Since 2.3.0, calling a method with @template T of TKey|TValue and @param (T is object ? T : Box<T>) $value from code holding (TValue is object ? TValue : Box<TValue>) reported Unable to resolve the template type T and an argument.type error. 2.2.x was already wrong here: T silently fell back to its bound, so it reported a return.type error at the call site instead. That error is gone now too.

There were two separate problems:

1. TypeCombinator::union() merged template arrays of different template types into one. TKey of array|TValue of array became TKey of array. So the else branch Box<T> of the conditional became Box<T of TKey of array>, and Box<TValue> could not match it.
2. UnionType::inferTemplateTypes() dropped the received members meant for a naked template member. For T|Box<T> receiving X|Box<Y>, Box<T> inferred T = Y and the naked T was skipped, so X was lost.

Changes

• src/Type/TypeCombinator.php (processArrayTypes(), new groupArrayTypesByTemplateType()): arrays are grouped by template type (name and scope), with non-template arrays in their own group. Each group is processed separately, so only arrays of the same template are merged. Covers TemplateArrayType, TemplateConstantArrayType (TA of array{a: int}|TB of array{a: int} used to collapse to TB), template lists, and template arrays next to plain arrays.
• src/Type/TypeCombinator.php (compareTypesInUnion()): the iterable merge (string[]|int[] → (string|int)[]) no longer applies to template types. TA of iterable|TB of iterable used to become plain iterable.
• src/Type/UnionType.php (accepts()): when the array|Traversable reading of a TemplateIterableType is not accepted, the template is checked member by member, the same way isSuperTypeOf() already treats it. Without this, TA|TB (both of iterable) did not accept itself once the union was kept apart. It also fixes (TKey&iterable)|... not being accepted as TKey|TValue, which 2.2.x got wrong too.
• src/Type/UnionType.php (inferTemplateTypes()): after the non-naked members have inferred, any remaining received member that no non-naked member infers anything from is inferred against the naked template members.
• turbo-ext/src/TypeCombinator.cpp, turbo-ext/src/UnionType.cpp: the same changes in the native mirrors.
• Probed and already correct: unions of different templates with non-array bounds (int, int<0, 5>, string, float, bool, object, a class, mixed, constant scalars, int|string).

Root cause

Union simplification and inference both treated template-typed members by their bound. In the array and iterable merges, two different templates with array/iterable bounds were folded into one type. The template-array code kept only the first template's name, which is unsound. The iterable merge widened to plain iterable, which loses the template. Template inference then could not match the narrowed conditional branch. Separately, the union inference rule "a naked template member only infers when no other member does" threw away argument parts that no other member could explain.

Test

• tests/PHPStan/Rules/Methods/data/bug-15431.php: the issue's playground code, nearly verbatim.
  • CallMethodsRuleTest::testBug15431 expects no errors.
  • ReturnTypeRuleTest::testBug15431 expects only the legitimate error inside unboxValue(): an object TKey might itself be a box. That error was also reported by 2.2.x.
• tests/PHPStan/Rules/Methods/data/bug-15431-iterable.php / ReturnTypeRuleTest::testBug15431Iterable: template iterables in unions are accepted as their templates.
• tests/PHPStan/Analyser/nsrt/bug-15431.php:
  • the conditional parameter type keeps both templates
  • T is inferred from conditional arguments
  • unions of template arrays, lists, constant arrays and iterables
  • T|Box<T>, (T is object ? T : Box<T>) and T|array<T> inference from mixed arguments

All new tests fail without the fix. The full suite passes with and without the turbo extension loaded, and make phpstan is clean.

Fixes phpstan/phpstan#15431

🤖 Generated with Claude Code