php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login

go to bug id or search bugs for

Doc Bug #64909 array_merge - Return value documentation incorrect/misleading
Submitted: 2013-05-23 14:04 UTC Modified: 2013-05-25 19:10 UTC
Votes:1
Avg. Score:1.0 ± 0.0
Reproduced:0 of 1 (0.0%)
From: tim dot hentenaar at gmail dot com Assigned:
Status: Not a bug Package: Documentation problem
PHP Version: 5.4.15 OS: N/A
Private report: No CVE-ID: None
View Add Comment Developer Edit
 [2013-05-23 14:04 UTC] 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

Patches

Add a Patch

Pull Requests

Add a Pull Request

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2013-05-24 17:57 UTC] 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-24 20:30 UTC] 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-25 19:10 UTC] salathe@php.net 
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.
 [2013-05-25 19:10 UTC] salathe@php.net
-Status: Open +Status: Not a bug
 
PHP Copyright © 2001-2024 The PHP Group
All rights reserved. 		Last updated: Thu Apr 18 23:01:27 2024 UTC