Doc #71739 [Com]: Parameter passing methods should be clearer

Edit report at https://bugs.php.net/bug.php?id=71739&edit=1 ID: 71739 Comment by: athalas at gmail dot com Reported by: athalas at gmail dot com Summary: Parameter passing methods should be clearer Status: Verified Type: Documentation Problem Package: Arrays related Operating System: Irrelevant PHP Version: 5.5.33 Block user comment: N Private report: N New Comment: That's it! You get the point. :) David Previous Comments: ------------------------------------------------------------------------ [2016-12-31 14:06:56] 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 13:11:30] 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-28 15:00:54] 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-03-08 11:16:01] 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. ------------------------------------------------------------------------ -- Edit this bug report at https://bugs.php.net/bug.php?id=71739&edit=1