@phpstan-assert annotation

roben

Could you please add support for the @phpstan-assert annotation for narrowing down types? It greatly helps with custom assertions.

See the "isObjectOfClass" example here: https://phpstan.org/writing-php-code/narrowing-types

JakubMisek

roben Good idea, will be added.

For now, we have @trace annotation to check the types of expressions in inlay hint:

/** @trace $expression */

roben

Thanks! But @assert differs a bit from @trace as it changes the type, that's whats important for us. It's more like a type cast than an assertion from a programmers view. But it is also different from @var because you can apply it to method parameters which then applies to any variable being passed into this method.

roben

Oh, I just noticed the isObjectOfClass() example uses @phpstan-assert-if-true. That's mostly the same but only applies if the return value of the method is true. For us, @phpstan-assert is more important, but maybe it is reasonable to implement all variants.

JakubMisek

I see, thanks! That will take some time to implement :)

JakubMisek

progress

[x] recognize phpstan-assert(-if-true|-if-false) tags
[x] parse type negation !
[x] infer types in code flow analysis when phpstan-assert annotates called function
[x] respect type negation
[ ] respect more complex expression, i.e. $this->getName()
[ ] respect phpstan-assert in composer packages

roben

Awesome, thanks!

JoeHoyle

@JakubMisek I have the following code:

/**
 * Check whether a variable is a WP_Error instance.
 *
 * @param mixed $thing
 *
 * @phpstan-assert-if-true WP_Error $thing
 */
function is_wp_error( $thing ) : bool {
	return false;
}


/**
 * @var array|WP_Error $sites
 */
$sites = null;

if ( is_wp_error( $sites ) ) {
	return;
}

$sites;

But $sites type doesn't seem to get narrowed:

JakubMisek

JoeHoyle thank you for the test case - working on it.

JakubMisek

JoeHoyle, fixed in the next update, thanks!