php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Doc Bug #71739 Parameter passing methods should be clearer
Submitted: 2016-03-08 11:16 UTC Modified: 2016-12-31 14:06 UTC
Votes:3
Avg. Score:4.3 ± 0.9
Reproduced:2 of 2 (100.0%)
Same Version:2 (100.0%)
Same OS:-2 (-100.0%)
From: athalas at gmail dot com Assigned:
Status: Verified Package: Arrays related
PHP Version: 5.5.33 OS: Irrelevant
Private report: No CVE-ID: None
 [2016-03-08 11:16 UTC] athalas at gmail dot com
Description:
------------
---
From manual page: http://www.php.net/function.array-filter
---

The trouble I found with this page is that a common requirement for the filter is to pass extra information for filtering, further than the array elements itself (for example, an external object or a flag that controls the filtering).

I think that the closure method (PHP 5.3+) for passing parameters to the callback function should be prioritized and shown very early in the function docs (in the first screen should be ideal), as is a PHP conformant and very nice/easy method to do it.

I always forget it and I always need a quick google search to find the snippet, that I think (and suggest) it should be in the main page, not even within comments, but as one of the usage examples of the array_filter() function.

Thanks for your consideration.

Regards,

David


Test script:
---------------
<?php

$obj2 = new stdClass();
$obj2->color = 'red';

$external_flag1 = 'green';

$data = array( 'green', 'red', 'blue' );

$filtered_data = array_filter($data, function($color) use ($external_flag1, $obj2) {
	return (($color == $obj2->color) || ($color == $external_flag1));
});

// will act depending on the color of $obj2 object and external_flag1 value
var_dump($filtered_data);

/*
returns:
// blue is removed as the array_filter result for that item is false
array(2) { [0]=> string(5) "green" [1]=> string(3) "red" }
*/


Expected result:
----------------
Looking at the first page of the array_filter() function documentation should expose the closure example (and/or maybe other methods) for a common method to pass external parameters into the callback for the filtering process.


Actual result:
--------------
Actually, you need to dig into the user comments (way down) to find an example, and you must remember yourself that this option exists at all. It should be more explicit, as it forces always to do extra search and find other docs to solve it.



Patches

Pull Requests

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2016-12-28 15:00 UTC] cmb@php.net
-Status: Open +Status: Not a bug -Package: Documentation problem +Package: Arrays related -Assigned To: +Assigned To: cmb
 [2016-12-28 15:00 UTC] cmb@php.net
There is already example 3 which uses closures as callback, so
there's no need to scroll further down. And actually, just
clicking the "callback" link in the function signature immediately
leads to the "Callbacks / Callables" man page, where several
possibilities (including closures) to use callbacks are shown.
 [2016-12-31 13:11 UTC] athalas at gmail dot com
Hi,

Thanks for your answer.

Actually I think you misunderstood the point.

I'm not talking of passing parameters ($item, or $key, $value) to the callback function itself, but the usage of the "use (...)" structure which is NOT documented in the function definition, nor in its examples and just loosely shown way down in the comments. 

Please look at my code, specifically:

  > $filtered_data = array_filter($data, function($color) use ($external_flag1,     $obj2) {


Not talking here about the usage of "$color", which is clearly documented in example #3 as you state, but the usage of "use ($external_flag1, $obj2, ...)" structure.

I think this usage pattern is quite useful and it should be promoted and clearly documented in the main page or in an additional and specific example, not just lost in some comment. I'm sure many developers don't know about it because of this, just like myself before.

Thanks for your reading, and I wish you all a happy 2017!!!

David
 [2016-12-31 14:06 UTC] cmb@php.net
-Status: Not a bug +Status: Verified -Assigned To: cmb +Assigned To:
 [2016-12-31 14:06 UTC] cmb@php.net
Ah, I see. While there is comprehensive documentation regarding
the use clause[1], it could indeed be made more prominent in the
array_filter() man page.

[1] <http://php.net/manual/en/functions.anonymous.php>
 [2016-12-31 16:10 UTC] athalas at gmail dot com
That's it! You get the point.

:)

David
 
PHP Copyright © 2001-2024 The PHP Group
All rights reserved.
Last updated: Sun Dec 01 20:01:29 2024 UTC