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 #52878 Incorrect return type
Submitted: 2010-09-18 06:21 UTC Modified: 2010-10-24 18:58 UTC
Votes:1
Avg. Score:3.0 ± 0.0
Reproduced:1 of 1 (100.0%)
Same Version:1 (100.0%)
Same OS:1 (100.0%)
From: jon at phpsitesolutions dot com Assigned: markskilbeck (profile)
Status: Closed Package: Documentation problem
PHP Version: Irrelevant OS:
Private report: No CVE-ID: None
View Developer Edit
Welcome! If you don't have a Git account, you can't do anything here.
If you reported this bug, you can edit this bug over here.
(description)
Block user comment
Status: Assign to:
Package:
Bug Type:
Summary:
From: jon at phpsitesolutions dot com
New email:
PHP Version: OS:

 

 [2010-09-18 06:21 UTC] jon at phpsitesolutions dot com 
Description:
------------
http://us.php.net/manual/en/memcached.getmultibykey.php

The docs state that the return type is void (public void 
Memcached::getMultiByKey), but then in the actual return description, it states 
Array or False, which would be "mixed".


This affects the overall docs page for Memcached, as well as the specific function 
description page.

There are other occurrences such as this one in the Memcached docs as well....

Patches

Pull Requests

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2010-09-19 14:48 UTC] markskilbeck@php.net 
Automatic comment from SVN on behalf of markskilbeck
Revision: http://svn.php.net/viewvc/?view=revision&revision=303569
Log: #52878 - fixes return type
 [2010-09-19 15:35 UTC] markskilbeck@php.net
-Status: Open +Status: Closed -Assigned To: +Assigned To: markskilbeck
 [2010-09-19 15:35 UTC] markskilbeck@php.net 
I've updated the documentation to reflect your suggestion.
 [2010-09-19 17:19 UTC] philip@php.net
-Status: Closed +Status: Analyzed
 [2010-09-19 17:19 UTC] philip@php.net 
Technically it should be 'array' and not 'mixed' as otherwise every 
method/function in the manual would be 'mixed'. The prototype includes what may 
happen on success.

That is, unless false is returned when no items are found (as opposed to some 
error or fail). I assume an empty array is returned in that case but if not then 
mixed is perfect. Either way, it could be clarified.
 [2010-09-20 12:42 UTC] markskilbeck@php.net 
Hi, Phillip.

I wasn't aware that only the success value should be documented. Anyway, most of the documentation I've seen shows functions that return FALSE on failure and any other value on success as a mixed return. This makes sense to me. However, getMultiByKey does return FALSE only on error, it seems.
 [2010-09-20 17:43 UTC] jon at phpsitesolutions dot com 
Whichever is the correct approach, I leave up to better minds @php.net (such as 
yourselves) to decide.
The main issue is to ensure that the "void" return type is corrected to at least 
array or mixed, as either would be more accurate than "void".


Just a suggestion regarding the array vs mixed debate, there does seem to be a 
definite inconsistency across PHP docs, so it would be nice to see a decision 
and then likely a process would need to be put in place to review the return 
types going forward, to make consistent?

Or maybe I'm just overthinking things :-)

Cheers
 [2010-09-20 17:57 UTC] philip@php.net 
The official stance is to designate the return type as the 'on success' values. If 
this were not the case, then every return value would be either 'mixed' or 'bool' 
with that assuming we ignore NULL. The 'return role' then may say something like  
'returns false on failure'

In the case of this function, it should be array.

As far as being consistent, that's always a goal. :)
 [2010-09-20 18:15 UTC] philip@php.net 
And to be clear, success means the function executed without bailing out. So fail 
could mean, for example, passing in the wrong type as a parameter, or using the 
function incorrectly.
 [2010-10-24 18:57 UTC] markskilbeck@php.net 
Automatic comment from SVN on behalf of markskilbeck
Revision: http://svn.php.net/viewvc/?view=revision&revision=304707
Log: #52878 - Fix return type; now 'array' instead of 'mixed'
 [2010-10-24 18:58 UTC] markskilbeck@php.net
-Status: Analyzed +Status: Closed
 [2010-10-24 18:58 UTC] markskilbeck@php.net 
This bug has been fixed in the documentation's XML sources. Since the
online and downloadable versions of the documentation need some time
to get updated, we would like to ask you to be a bit patient.

Thank you for the report, and for helping us make our documentation better.
 
PHP Copyright © 2001-2026 The PHP Group
All rights reserved. 		Last updated: Thu Oct 08 16:00:01 2026 UTC