Return null from ArgumentsNormalizer::reorderArgs() when positional args after named args create holes beyond parameter count

[phpstan-bot]

Summary

When calling a function with positional arguments after a named argument (e.g. \PHPStan\dumpType(1, 2, 3, d: 'foo', 5)), PHPStan crashed with an internal error "Parameter signatures cannot have holes" instead of reporting proper errors about the invalid argument order.

Changes

• src/Analyser/ArgumentsNormalizer.php: Replace throw new ShouldNotHappenException(...) with return null in the hole-filling loop of reorderArgs() when a hole index exceeds the parameter signature length.
• tests/PHPStan/Analyser/ArgumentsNormalizerTest.php: Added two test cases to dataReorderInvalid:
  • Positional arg after named arg with a variadic parameter (mirrors the exact reproducer from the issue)
  • Positional arg after named arg without a variadic parameter

Root cause

In ArgumentsNormalizer::reorderArgs(), positional arguments use their original index from the $callArgs array as keys in $reorderedArgs. When a named argument sits between positional arguments (invalid PHP: "Cannot use positional argument after named argument"), the named arg is handled separately (placed in additionalNamedArgs or appendArgs), but the positional arg following it keeps its original index. This creates a gap in the $reorderedArgs array at an index that has no corresponding entry in $signatureParameters, causing the hole-filling loop to throw.

The fix returns null instead, which all callers already handle gracefully — they either fall back to the original (unreordered) arguments or skip the check. The normal argument validation rules then correctly report "Named argument cannot be followed by a positional argument."

Since all callable types (functions, methods, static methods, constructors, call_user_func) share the same reorderArgs() method, the fix covers all of them automatically. Verified with manual testing of FuncCall, MethodCall, StaticCall, New_, and call_user_func.

Test

• Added two unit test cases in ArgumentsNormalizerTest::dataReorderInvalid that reproduce the crash and verify reorderArgs() returns null for these invalid argument patterns.
• All 12045 existing tests pass. PHPStan self-analysis reports no errors.

Fixes phpstan/phpstan#14596

[staabm]

since this fixes a crash-bug it needs a test in AnalyserIntegrationTest

[phpstan-bot]

Done. Added an integration test in AnalyserIntegrationTest::testBug14596() that reproduces the exact crash from the issue (\PHPStan\dumpType(1, 2, 3, d: 'foo', 5) — positional arg after named arg). Verified the test fails with the original ShouldNotHappenException before the fix and passes after. All 12046 tests pass and make phpstan reports no errors.

[staabm]

@phpstan-bot cover this example also in CallMethodsRuleTest, CallStaticMethodsRuleTest and assert expected errors

[phpstan-bot]

Pushed. Added testBug14596() to both CallMethodsRuleTest and CallStaticMethodsRuleTest, with a shared test data file at tests/PHPStan/Rules/Methods/data/bug-14596.php that exercises method calls and static method calls with positional arguments after named arguments. Both tests assert the expected "Named argument cannot be followed by a positional argument." error. All 12048 tests pass and make phpstan reports no errors.