Doc #67038 [Com]: in_array returns null

Edit report at https://bugs.php.net/bug.php?id=67038&edit=1 ID: 67038 Comment by: kilbyc at bellsouth dot net Reported by: kilbyc at bellsouth dot net Summary: in_array returns null Status: Not a bug Type: Documentation Problem Package: Documentation problem Operating System: Windows 7 PHP Version: 5.5.11 Block user comment: N Private report: N New Comment: 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. Previous Comments: ------------------------------------------------------------------------ [2014-04-08 18:03:34] kalle@php.net 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. ------------------------------------------------------------------------ [2014-04-07 17:43:50] kilbyc at bellsouth dot net Still a problem with consistency in the docs. http://www.php.net/manual/en/function.fopen.php lists the warning and undefined behavior. ------------------------------------------------------------------------ [2014-04-07 16:37:09] mfonda@php.net 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." ------------------------------------------------------------------------ [2014-04-07 16:20:22] kilbyc at bellsouth dot net 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. ------------------------------------------------------------------------ [2014-04-07 16:02:21] kilbyc at bellsouth dot net Description: ------------ http://us1.php.net/in_array is at best misleading, at worst, blatantly wrong. The documentation clearly states that in_array returns bool, true, false. Null is not an acceptable value in that list. Also, the manual does not advise that this function may throw warnings. This has been ignored for a while. https://bugs.php.net/bug.php?id=39788 Test script: --------------- C:\php5.5>php --version PHP 5.5.11 (cli) (built: Apr 2 2014 16:03:05) Copyright (c) 1997-2014 The PHP Group Zend Engine v2.5.0, Copyright (c) 1998-2014 Zend Technologies C:\php5.5>php -r "var_export(in_array('thing', null));" Warning: in_array() expects parameter 2 to be array, null given in Command line NULL Expected result: ---------------- Update the manual to say that in_array issues Warning. And: Either returns NULL if the array is null. OR Fix the function to return false is the array is null. ------------------------------------------------------------------------ -- Edit this bug report at https://bugs.php.net/bug.php?id=67038&edit=1