Prevent "Unresolvable type" errors when mapping constant arrays

[phpstan-bot]

Summary

With bleeding edge enabled, calling a generic function whose return type is inferred
from an arrow function returning array_map(fn (Someenum $t) => $t->value, Someenum::cases())
produced false-positive errors:

Return type of call to function doFoo contains unresolvable type.
Parameter #1 $callable of function doFoo contains unresolvable type.

even though the inferred type (array{'foo'}) was correct. This PR stops array_map
(and other mapValueType callers) from planting an ErrorType inside the sealed
array's internal unsealed descriptor.

Changes

• src/Type/Constant/ConstantArrayType.php: mapValueType() no longer applies the
  callback to the unsealed value type when the array is sealed (isUnsealed()->no()),
  i.e. when that slot is the explicit-never sentinel. It is left untouched for sealed
  arrays and still mapped for genuinely/maybe-unsealed arrays.
• Added a rule regression test tests/PHPStan/Rules/Functions/Bug14844Test.php (+ data
  data/bug-14844.php) running CallToFunctionParametersRule under bleeding edge and
  asserting no errors.
• Added a type-inference regression test tests/PHPStan/Analyser/nsrt/bug-14844.php
  pinning the inferred type to array{'foo'}.

Root cause

In bleeding edge a sealed ConstantArrayType carries an unsealed descriptor of
[never, never] (explicit never) representing "this array has no extra elements". The
value-type slot of that sentinel is not a real element type.

ConstantArrayType::mapValueType() mapped the unsealed value type through the supplied
callback. For array_map the callback resolves the user callback against the array's
value type; given the never sentinel it evaluates never->value (an enum-case
property fetch on never), which produces an ErrorType. That ErrorType was stored
inside the resulting array's unsealed slot — invisible in describe() but visited by
UnresolvableTypeHelper, which walks the entire type tree and flags any ErrorType,
hence the bogus "contains unresolvable type" reports.

The pattern is "transforming the sealed sentinel as if it were a real element type". The
single affected location is mapValueType, which is the chokepoint for every value-map
operation (array_map via ArrayMapFunctionReturnTypeExtension, the str_replace family
via ReplaceFunctionsDynamicReturnTypeExtension, etc.).

Test

• Bug14844Test::testBug14844 reproduces the reported false positives under bleeding
  edge and asserts the call analyses cleanly. It fails before the fix with the two
  unresolvableType errors and passes after.
• nsrt/bug-14844.php asserts the inferred type is array{'foo'}.
• Probed analogous cases (all confirmed routed through and fixed by the same
  mapValueType guard, no separate bug): str_replace over a mapped enum-case array,
  nested array_map, passing the sealed array through a generic identity function,
  array spread [...$arr], and + array union. The sibling transforms
  traverse / traverseSimultaneously only propagate existing types and never plant
  the ErrorType, so they need no change.

Fixes phpstan/phpstan#14844

[staabm]

do we have similar bugs in other areas where we check explictly for $this->unsealed === null but do not check $this->isUnsealed()->no()?

if so, come up with test-cases and fixes

[phpstan-bot]

Pushed. Here's my response to the reviewer's question.

Addressing the review

do we have similar bugs in other areas where we check explicitly for $this->unsealed === null but do not check $this->isUnsealed()->no()?

I audited every site in ConstantArrayType that reads or transforms the [never, never] unsealed sentinel, and verified the answer empirically (by reverting the mapValueType guard and exercising each operation under bleeding edge).

Conclusion: mapValueType is the unique reproducible site. No other source fix is warranted. Here's why:

• Read sites (getArray, getOffsetValueType, inferTemplateTypes, getKeysArray/getValuesArray, degradeToGeneralArray, etc.) are already gated by isUnsealed()->yes() && $this->unsealed !== null, which excludes the sentinel by construction. getIterableValueType() likewise never includes the sentinel.

• Transform sites — the structural twins traverse, traverseSimultaneously, generalizeValues, filterArrayRemovingFalsey, changeKeyCaseArray — do touch the sentinel via $this->unsealed !== null, but they only ever map never → never (structural type traversal, generalize, falsey-removal guarded by a NeverType check). The sentinel is preserved, so no ErrorType is planted.

• Only mapValueType applies a value-projecting callback — array_map's user-closure body, which evaluates never->value (an enum-case fetch on never) and yields ErrorType. That's the one that needed the isUnsealed()->no() guard.

The empirical test was decisive: with the fix reverted, array-rebuilding ops (array_reverse, array_values, array_merge, spread) drop and recreate the sentinel (clean), array-propagating ops (identity, +, array_filter) merely carry through whatever's already there, and only array_map plants the ErrorType.

What I added

Since the PR description said several analogous cases were manually probed but only array_map got an automated test, I converted that probe matrix into permanent regression coverage:

• tests/PHPStan/Rules/Functions/data/bug-14844-siblings.php + Bug14844Test::testBug14844Siblings — runs the whole operation family (nested array_map, str_replace, generic pass-through, +, spread, array_filter, array_reverse, array_values, array_merge, array_change_key_case, plain sealed literals) under bleeding edge and asserts no unresolvableType errors.

I confirmed these tests fail without the mapValueType guard (4 cases surface the bogus error) and pass with it. make phpstan and the affected suites are green.

[staabm]

would it make sense to prevent writing a type into $this->unsealed which is considered->isUnsealed()->no() instead ?

[phpstan-bot]

I've addressed the reviewer's suggestion. Here's a summary:

What the reviewer asked

would it make sense to prevent writing a type into $this->unsealed which is considered ->isUnsealed()->no() instead?

Rather than guarding the single mapValueType call site, the reviewer suggested preventing the bad write at the source.

What I changed

src/Type/Constant/ConstantArrayType.php:

1. Constructor normalization (the new fix): Whenever a ConstantArrayType is constructed with a sealed unsealed descriptor — i.e. the unsealed key is the explicit never sentinel, exactly the isUnsealed()->no() condition — the constructor now forces the unsealed value slot back to new NeverType(true). Since the value slot of a sealed array represents "no extra elements," it is never a real element type, so any projected/transformed type a caller tries to plant there (e.g. the ErrorType from mapping never->value) is discarded.

2. Reverted the mapValueType per-call-site guard back to its simpler original form. recreate() routes every transform through new self(...), so the constructor normalization now protects all transform sites (mapValueType, traverse, generalizeValues, etc.) centrally — a strictly more robust answer to staabm's earlier "do other areas have the same bug?" question.

Verification

• Confirmed the constructor normalization is load-bearing: with it neutralized (and the old guard already removed), the bug resurfaces with 8 bogus unresolvableType errors across the sibling cases; with it in place, all green.
• Bug14844Test (both testBug14844 and testBug14844Siblings) — pass.
• nsrt/bug-14844.php type inference — passes (array{'foo'}).
• ConstantArrayTypeTest (182), full NodeScopeResolverTest (1662), all tests/PHPStan/Type/ (2961) — green.
• make phpstan — no errors.

Committed as d81b07fde and pushed.

[staabm]

add one more test in Bug14844Test for https://phpstan.org/r/caf9ff47-8bf2-4d60-9786-8ce9c1273fa7 (which proves the initial bug is not related to enums only)

[phpstan-bot]

Done. I addressed staabm's review by adding the requested test for the playground.

What I did

The playground is a class-constant variant of the same sealed-sentinel bug: instead of mapping an enum-case property fetch ($type->value), it maps a class-constant fetch ($type::FOO) through array_map over [new Someclass()]. It produces the identical false positives:

Return type of call to function doFoo contains unresolvable type.
Parameter #1 $callable of function doFoo contains unresolvable type.

Changes

• tests/PHPStan/Rules/Functions/data/bug-14844-class-const.php — new data file with the class-constant variant from the playground.
• tests/PHPStan/Rules/Functions/Bug14844Test.php — added testBug14844ClassConst() running CallToFunctionParametersRule under bleeding edge and asserting no errors.

Verification

• Test catches the bug: with the constructor normalization temporarily disabled, the test fails with exactly the two unresolvableType errors (lines 34/35). With the fix in place it passes — confirming it routes through the same mapValueType chokepoint.
• All 3 tests in Bug14844Test pass; make phpstan is clean.
• Committed as 9a32cc9e5 and pushed.