[HELP NEEDED] feat: phpstan-assert with throws annotation

[PrinsFrank]

I have a library, that has treatPhpDocTypesAsCertain set to false, as there are user-facing methods with array shapes that need to be checked to make sure that no invalid arrays are passed by the user of the package as not everyone uses phpstan. I also have checked exceptions enabled. The combination of these results in undocumentable methods;

/**
 * @param array<stdClass> $foo
 * @phpstan-assert array<stdClass> $this->foo
 */
public function __construct(
    public readonly array $foo
) {
    foreach ($this->foo as $bar) {
        if ($bar instanceof stdClass === false) {
            throw new \InvalidArgumentException();
        }
    }
}

This results in the following errors:

Asserted type array<stdClass> for $foo with type array<stdClass> does not narrow down the type.
Method Foo::__construct() throws checked exception InvalidArgumentException but it's missing from the PHPDoc @throws tag.

I don't want to mark all InvalidArgumentExceptions as unchecked, but I don't want to let the exception bubble up into methods that do properly call the constructor with an array of stdClass elements:

new Foo([new stdClass]);

The solution?

If a new argument is added to the @phpstan-assert annotation with a class-string of an exception both errors would disappear:

• The unchecked exception check can read the thrown exception from the phpstan-assert annotation
• The 'does not narrow down the type' error is not true anymore because the phpstan-assert annotation introduces a thrown exception when the type is not correct.

/**
 * @phpstan-assert array<stdClass> $foo \InvalidArgumentException
 */

Would this be something that you would be open to? I started writing the code for this, but this will take quite a lot of time so I'd first like to check if this will even have a chance to get merged.

[phpstan-bot]

You've opened the pull request against the latest branch 1.11.x. If your code is relevant on 1.10.x and you want it to be released sooner, please rebase your pull request and change its target to 1.10.x.

[ondrejmirtes]

Hi, if you're dealing with a PHPStan bug, please open a bug report with a reproduction instead of a pull request, thanks.