This is documented at http://php.net/manual/en/functions.internal.php — it's been 
previously decided not to include this on each function page.

Unfortunately, the documentation on that page specifically states:
"In this case it will likely return NULL but this is just a convention, and 
cannot be relied upon."

I believe it would be beneficial for the individual page to explicitly mention 
the return on failure code (as many other pages do) to be more concise. Some 
users may not have seen the Internal built-in functions page, and may have 
missed valuable information. Even if one had read that page, the page itself 
states that it remains an unreliable source of information for the return code.

In theory, I agree with you, but the main reason for not doing this is a lack of 
resources — nobody on the documentation team has the time to audit each function 
for this (it comes down to whether the function internally uses 
zend_parse_parameters(), which most — but not all — do), and it would be just as 
bad to blanket document this and be wrong about the functions that don't use zpp.

It sucks, but that's kind of where we're at. Sorry.