It gets worse

What about the people who read the manual and see the bool sig, and therefore implement something like:

$is_authorized = in_array('user',$roles)!==false;//and $roles failed to init

The developer doesn't know there is a potential warning there, or to look for a null.

Built-in PHP functions will generally return null if an invalid argument is passed. This is documented at http://us1.php.net/manual/en/functions.internal.php:

"Note: 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."

Still a problem with consistency in the docs.

http://www.php.net/manual/en/function.fopen.php lists the warning and undefined behavior.

Sorry, but your problem does not imply a bug in PHP itself.  For a
list of more appropriate places to ask for help using PHP, please
visit http://www.php.net/support.php as this bug system is not the
appropriate forum for asking support questions.  Due to the volume
of reports we can not explain in detail here why your report is not
a bug.  The support channels will be able to provide an explanation
for you.

Thank you for your interest in PHP.

As mentioned by mfonda@, this is the same with all internal functions to return NULL if parameter parsing fails.

The example you mentioned, fopen(), only lists the error you get if a file fails to open, for example:

<?php
$fp = fopen('/this/does/not/exists', 'r');
?>

And that you can supress that E_WARNING with the @-operator, not the actual parameter parsing. I agree that we should maybe make that more clear but we cannot state that on every single function page and we request userland developers to look at the manual appendixes for such cases.

I didn't open this as a bug against the language, but as a doc issue. The docs are inconsistent. As you yourself point out it should be made more clear. As for the "cannot state that on every single function page" why not? javadoc, phpdoc, any number of automatic parsers can strip this type of information from well documented code and generate well formed docs.

As for the "manual appendixes for such cases", what appendixes? Do you mean the User Contributed Notes? Have you read the comments? 7/10 comments are odd, if not wrong, 1 just references another comment, 1 is a security hole if implemented, and 1 is actually useful. There is no real rhyme or reason to them, and as a developer, I shouldn't be expected to have the community know how the language actually works, if no one actually involved with the language is releasing official documents that state how the language works.