Skip to content

Keep the PHP 8 throw types of built-in functions in a version range below PHP 8 - #7100

Open
SanderMuller wants to merge 1 commit into
phpstan:2.3.xfrom
SanderMuller:throw-type-version-range
Open

SanderMuller wants to merge 1 commit into
phpstan:2.3.xfrom
SanderMuller:throw-type-version-range

Conversation

@SanderMuller

Copy link
Copy Markdown
Contributor

With a PHP version range such as phpVersion: {min: 70400, max: 80500}, a catch of ValueError around these calls is reported as dead:

try {
	array_chunk([1], $length);
} catch (\ValueError $e) { // Dead catch - ValueError is never thrown in the try block.
}

PHP 8 throws ValueError here when $length is below 1. The same happens for str_split(), min(), max(), the printf() family, version_compare(), array_combine() and round().

PHPStan reads the stubs for the minimum version of the range. Below PHP 8, BetterReflection removes the @throws tags that PHP 8 added, or it picks a PHP 7 stub without them. So getThrowType() returns null. The throw type extensions of these functions returned that null, and FuncCallHandler then adds no throw point. Functions without an extension are not affected, because with the default implicitThrows a null throw type gives an implicit throw point.

The fix follows #6539, which added the same fallback to the range() extension:

  • The extensions fall back to ValueError when getThrowType() is null.
  • min() and max() returned VoidType when the range did not certainly include PHP 8. They now do that only when it certainly does not.
  • array_combine() had no version check. It now returns null when the PHP version is below 8. This keeps the old result for a PHP 7 version.
  • The printf() family adds ValueError, and ArgumentCountError for the functions that take the values as arguments. A null check is not enough there, because the stubs keep ArgumentCountError for vprintf() and vfprintf().

I left out unserialize(), because #6624 changes the same extension.

The new cases in unthrown-exception-php-version-range.php fail without the change in src. With a probe file, the errors do not change for a fixed PHP 7.4, 8.0 or 8.5 version, or for an 8.0 to 8.5 range.

🤖 Generated with Claude Code

…elow PHP 8

With a PHP version range such as 7.4 to 8.5, the stubs of the minimum
version do not have the @throws tags that PHP 8 added, so
getThrowType() returns null. The throw type extensions of array_chunk(),
str_split(), min(), max(), the printf() family, version_compare(),
array_combine() and round() returned that null, and a catch of
ValueError around these calls was reported as dead.

These extensions now fall back to ValueError (and ArgumentCountError
for the printf() family) when the range only maybe includes PHP 8, like
the range() extension does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@staabm

staabm commented Nov 17, 2026

Copy link
Copy Markdown
Contributor

I am not sure about this one.

is this something which really needs custom handling in every *ThrowTypeExtension?
or can/should it be fixed in the phpstan-src core?

@SanderMuller

Copy link
Copy Markdown
Contributor Author

Partly, yes. BetterReflection removes the @throws tags that PHP 8 added when the minimum of the range is below PHP 8. If the stubber decided on the maximum instead, 5 of the 9 functions would need no change in their extension. I checked this locally with the base src and the stubber patched to keep the tags.

The other 4 still need an extension change:

  • min() and max(): the extension returns VoidType unless every version in the range is PHP 8 or later.
  • array_combine() and version_compare(): the stubber picks a PHP 7 variant of the stub, which has no @throws.

The core part needs a change in ondrejmirtes/better-reflection, for example a maximum version for the stubber. It also changes the throw type of the other functions and methods in its PHP 8 list. Do you prefer that, with only the 4 extension changes left here?

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.

2 participants