Declare Throwable as the unserialize() throw type unless allowed_classes provably forbids all classes

[phpstan-bot]

Summary

unserialize() runs user code: autoloaders, __wakeup(), __unserialize() and Serializable::unserialize(). Any of these can throw any exception. The throw type extension only declared TypeError, so a catch (Exception $e) around unserialize($s) was reported as Dead catch - Exception is never thrown in the try block.

With this change, the extension returns Throwable whenever the call may instantiate classes.

Changes

• src/Type/Php/UnserializeFunctionThrowTypeExtension.php:
  • Return Throwable when there are no options, when the options are not a constant array, when arguments are named or unpacked, or when allowed_classes is not provably false/[].
  • When no class can be instantiated, valid options give void. Invalid options give the stub's TypeError|ValueError on PHP 8 and void on PHP 7.
  • PHP 7 used to always get void. It now gets Throwable too when classes are allowed, because magic methods can throw there as well.
• Probed analogous builtins that call user code:
  • serialize() already has an implicit throw point.
  • sprintf()/printf() do not accept objects in PHPStan's signatures.
  • json_encode() of a JsonSerializable can also throw from jsonSerialize(). I left it unchanged: returning Throwable would swallow the checked JsonException for JSON_THROW_ON_ERROR, and a dynamic throw type extension can only return a single Type.

Root cause

The extension treated unserialize() as if its only possible exceptions were those thrown by the engine: option validation and typed-property mismatches. It ignored the user code that unserialize() runs for every object it restores. So every catch of a non-TypeError exception looked dead, including ValueError catches when classes were allowed.

Test

• tests/PHPStan/Rules/Exceptions/data/bug-15329.php: the reproducer from the issue. Before the fix it reported a dead catch; now it reports nothing.
• tests/PHPStan/Rules/Exceptions/data/unserialize-throw-type.php: updated expectations. Catches around calls that may instantiate classes are no longer reported. New cases cover:
  • invalid options with allowed_classes => false (ValueError is thrown on PHP 8 and is dead on PHP 7)
  • catch (Exception) with allowed_classes => [] (still dead)
  • catch (Exception) with allowed_classes => true (not dead)

Fixes phpstan/phpstan#15329

🤖 Generated with Claude Code