Doc #64909 [Opn->Nab]: array_merge - Return value documentation incorrect/misleading

Edit report at https://bugs.php.net/bug.php?id=64909&edit=1 ID: 64909 Updated by: salathe@php.net Reported by: tim dot hentenaar at gmail dot com Summary: array_merge - Return value documentation incorrect/misleading -Status: Open +Status: Not a bug Type: Documentation Problem Package: Documentation problem Operating System: N/A PHP Version: 5.4.15 Block user comment: N Private report: N New Comment: This behaviour is common across almost all functions, and we have a note to that effect on the "Internal (built-in) functions" page (http://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. The documentation team have discussed this in the past and determined that it would be impractical and confusing for readers if such a note were to be added to every-single-function in the manual. Previous Comments: ------------------------------------------------------------------------ [2013-05-24 20:30:53] tim dot hentenaar at gmail dot com Hi Pete, Yes, that was my point exactly. In the example code, I didn't adhere to the signature of the function by passing a non-array argument. The method also doesn't adhere to its own signature by returning a non-array value. :P If one assumes, by the docs, that array_merge() will return the 'resulting array', then I would expect that even in case of error that array_merge() will still return something (empty or otherwise) of the 'array' type. It should probably be noted in the "Return values" section that NULL might possibly be returned in that particular case, since the implementation of array_merge() clearly does. ------------------------------------------------------------------------ [2013-05-24 17:57:08] pete at petermcdonald dot co dot uk There is quite a large warning on the documentation advising that php5 MUST have arrays passed to it. It might be worth adding to the note advising of unexpected behaviour if array's are not passed but you have not adhered to the signature of the function therefore unexpected behaviour is for want of a better phrase, expected. ------------------------------------------------------------------------ [2013-05-23 14:04:28] tim dot hentenaar at gmail dot com Description: ------------ --- From manual page: http://www.php.net/function.array-merge#refsect1- function.array-merge-returnvalues --- "Return Values: Returns the resulting array." The documentation for the return values of array_merge() is not entirely correct. In fact, array_merge() will return NULL if one of its arguments is not an array, along with giving a warning. Either the documentation is wrong, and returning NULL is intended here, in which case the documentation needs to be updated; or array_merge() should be made to return an array (empty, or perhaps the initial array) in this case, since the documentation indicates that array_merge() returns an array. Test script: --------------- <?php # This shows that $r is actually assigned NULL. $r = array_merge(array('a' => 'b'),1); var_dump($r); ?> Expected result: ---------------- That the variable $r should be an array, with or without the warning. Actual result: -------------- Warning: array_merge(): Argument #2 is not an array in /home/tim/php/array_merge_test.php on line 4 NULL ------------------------------------------------------------------------ -- Edit this bug report at https://bugs.php.net/bug.php?id=64909&edit=1