Keep a by-ref writeback's native type only when the written-back type fits it

[SanderMuller]

A regression in 2.2.15 from #6463. With treatPhpDocTypesAsCertain: false, this reports an error that 2.2.14 did not:

function offsetCapture(string $s): ?string
{
	if (! preg_match('/(a)(b)?/', $s, $m, PREG_OFFSET_CAPTURE)) {
		return null;
	}

	return isset($m[2]) ? $m[2][0] : null;
}

Offset 2 on *NEVER* in isset() always exists and is not nullable.

array_key_exists(2, $m) and $m[2] ?? null report the same way. I found no issue for it.

Cause. Since #6463, the native type after a by-ref argument is the parameter's own type. For a builtin, that is its signature map entry, and preg_match's &$matches is string[]. With PREG_OFFSET_CAPTURE each element is an array{string, int}, so the guard intersects the offset-capture shape with array<string>, and the native type becomes *NEVER*. Without the flag the elements are strings, which is why only this case breaks. Bisected: 3f97b5a57 is clean and 091f2cfc4 is the first bad commit.

The same happens to a userland @param-out that contradicts its declaration. PHP checks a by-ref parameter's type only on the way in. So int &$v with @param-out string really does hold a string afterwards, but the native type said int.

Fix. Keep the parameter's own type as the native type only when the written-back type is a subtype of it. Otherwise fall back to mixed. Where the two agree, as in #6463's bug-15250.php cases, nothing changes.

Trade-off. The fallback is mixed, not the nearest type that fits. After a PREG_OFFSET_CAPTURE match, a later is_array($m) is therefore no longer reported as always true with treatPhpDocTypesAsCertain: false. 2.2.14 did report it. A union with the written-back type would keep that. But it would put the PHPDoc shape back into the native type, which is what #6463 set out to stop.

Tests.

• nsrt/by-ref-writeback-native-type.php: offsetCapture() and userlandParamOut() fail without the change, with *NEVER* and int. noFlags() passes either way and guards the case that must not change.
• IssetRuleTest::testPregMatchOffsetCaptureWithoutTreatPhpDocTypesAsCertain() fails without the change with the reported error.

What else I checked.

• The native type after sort, preg_match without flags, preg_match_all, str_replace, exec, parse_str, similar_text, array_push and settype is the same before and after.
• A 4.5k-file project analysed with treatPhpDocTypesAsCertain: false gives the same 3106 errors before and after.
• make phpstan is clean. In make tests, the only failure is MissingCheckedExceptionInMethodThrowsRulePhp74Test::testInternalErrors, which fails the same way on 2.2.x without this change on my machine.
• On 2.3.x the same code sits in ArgumentsHandler.php, so the merge-up needs the same change there.

🤖 Generated with Claude Code

[ondrejmirtes]

We don't need to evaluate this for the ternary else (when $byRefType is assigned to $byRefNativeType). Feel free to write an ordinary if instead of the ternary above.

[SanderMuller]

Done in 3ee2eae.