trait_exists() returns nullable value, according to psalm stubs

[Ocramius]

See Roave/BetterReflection#983 (comment)
See https://psalm.dev/r/c41a43805d

In vimeo/psalm:4.18.1, trait_exists() is declared as trait_exists(string): ?bool: it should perhaps return bool at all time (not nullable).

<?php

function traitDoesIndeedExist(string $traitName): bool
{
    return trait_exists($traitName);
}

Produces

Psalm output (using commit c7d938b): 

ERROR: NullableReturnStatement - 5:12 - The declared return type 'bool' for traitDoesIndeedExist is not nullable, but the function returns 'bool|null'

ERROR: InvalidNullableReturnType - 3:51 - The declared return type 'bool' for traitDoesIndeedExist is not nullable, but 'bool|null' contains null
 
Psalm detected 1 fixable issue(s)

Definition seems to be imprecise in https://github.com/vimeo/psalm/blob/f1c4b62f5c65e887892e768dbaff6207ded14cee/dictionaries/CallMap.php

/cc @voku

[psalm-github-bot]

I found these snippets:

https://psalm.dev/r/c41a43805d

<?php

function traitDoesIndeedExist(string $traitName): bool
{
    return trait_exists($traitName);
}

Psalm output (using commit c7d938b):

ERROR: NullableReturnStatement - 5:12 - The declared return type 'bool' for traitDoesIndeedExist is not nullable, but the function returns 'bool|null'

ERROR: InvalidNullableReturnType - 3:51 - The declared return type 'bool' for traitDoesIndeedExist is not nullable, but 'bool|null' contains null

[AndrolGenhald]

The documentation is contradictory, it gives a return type of bool but says "Returns true if trait exists, false if not, null in case of an error."

I don't know how to read PHP's source with all it's preprocessor stuff well enough to say for sure, but I think this might have changed for PHP 7. I would guess that this would cause a null return value, but since PHP 7, as far as I can tell, it looks like it should only return bool. I could easily be wrong about that though.

[AndrolGenhald]

Here's a case where it returns null for PHP < 8.0: https://3v4l.org/XpHmh.
Not sure how much we care about that since we should be showing an issue for incorrect parameters anyway.

[Ocramius]

Indeed, assuming the function is defined as having 2 parameters, then : bool return should be OK.

[weirdan]

Not sure how much we care about that

We don't. Psalm has a policy of ignoring ZPP nulls like that.

[orklah]

We have an unofficial rule where any type returned only when the params are wrong (and are reported by Psalm) can be ignored in our callmaps to avoid cluttering

[orklah]

Well, I think we can safely fix that in callmaps. Anyone want to create the PR? :)

[Ocramius]

@orklah sorry, took me a while to actually get to clone + change the file (github editor does not allow for that anymore, due to its size :D )

[cmb69]

JFTR: ZPP failures are not supposed to be documented in the PHP manual for each function/method; there is already a general clause regarding internal functions:

If the parameters given to a function are not what it expects, such as passing an array where a string is expected, the return value of the function is undefined. In this case it will likely return null but this is just a convention, and cannot be relied upon. As of PHP 8.0.0, a TypeError exception is supposed to be thrown in this case.

So yes, this is a php/doc-en bug, which has just been fixed.

[AndrolGenhald]

@cmb69 Thanks for the info, I'll report it next time I notice one.

[Ocramius]

Ref: php/doc-en@de99fc7

Seems like nullability wasn't documented in the docbook types, but just in the description.

[cmb69]

@Ocramius, the signatures are autogenerated from the stub files now, but occassionally related changes in other parts of the docs are overlooked.